Skip to content

ReturnInfo class

Jump to bottom Edit New page
Gregor Leban edited this page Nov 20, 2020 · 21 revisions

When you make a query and ask for a list of articles or events, you will see a parameter named returnInfo which expects an instance of a class of type ReturnInfo. Similarly, the parameter appears for several other query types, such as trending concepts or info about sources or categories.

ReturnInfo is a class that can be used to specify which properties should be returned for each returned data type (events, articles, concepts, ...). The format in which different properties for individual data types are returned is described in detail in the Data Models page. The ReturnInfo class is just used to specify if a certain property should be included in the returned output or not. The constructor of the class accepts the following arguments:

ReturnInfo(
    articleInfo = ArticleInfoFlags(),             # details about the articles to return
    eventInfo = EventInfoFlags(),                 # details about the events to return
    sourceInfo = SourceInfoFlags(),               # details about the news sources to return
    categoryInfo = CategoryInfoFlags(),           # details about the categories to return
    conceptInfo = ConceptInfoFlags(),             # details about the concepts to return
    locationInfo = LocationInfoFlags(),           # details about the locations to return
    storyInfo = StoryInfoFlags(),                 # details about the stories to return
    conceptClassInfo = ConceptClassInfoFlags(),   # details about the concept classes to return
    conceptFolderInfo = ConceptFolderInfoFlags()) # details about the concept folders to return

For each of the data types, the default flags are set to return the most common set of parameters. In most cases you will not need to modify them.

Note that not all specified types are relevant for all requests. For example, if you are requesting a stream of new articles, then parameters about events (eventInfo) will be ignored since your output will not include any events.

We will now describe the individual settings that you can set in order to determine which properties to retrieve.

ArticleInfoFlags

Specifies what information about an article should be returned by the API call. The default constructor for ArticleInfoFlags looks as follows:

ArticleInfoFlags(bodyLen = -1,
    basicInfo = True,
    title = True,
    body = True,
    url = True,
    eventUri = True,
    authors = True,
    concepts = False,
    categories = False,
    links = False,
    videos = False,
    image = True,
    socialScore = False,
    sentiment = True,
    location = False,
    dates = False,
    extractedDates = False,
    originalArticle = False,
    storyUri = False)
  • bodyLen: determines the maximum length of the article body (use -1 for full body (default), 0 for empty)
  • basicInfo: core article information
  • title: article title
  • body: article body
  • url: article URL
  • eventUri: URI of the event to which the article belongs
  • authors: the list of authors of the news article
  • concepts: the list of concepts mentioned in the article. Properties are set by ConceptInfoFlags().
  • categories: the list of categories assigned to the article. Properties are set by CategoryInfoFlags().
  • links: links identified in the news article
  • videos: URLs to the videos identified in the article
  • image: URL to the image associated with the article
  • socialScore: information about the number of times the article was shared on different social media
  • sentiment: article sentiment
  • location: the geographic location that the event mentioned in the article is about. Properties are set by LocationInfoFlags().
  • dates: different dates associated with the crawling of the news article
  • extractedDates: the list of dates found mentioned in the article
  • originalArticle: if the article is a duplicate, this will provide information about the original article. Properties are set by ArticleInfoFlags().
  • storyUri: URI of the story (cluster) to which the article belongs

EventInfoFlags

Specifies what information about an event should be returned by the API call. The default constructor for EventInfoFlags looks as follows:

EventInfoFlags(title = True,
    summary = True,
    articleCounts = True,
    concepts = True,
    categories = True,
    location = True,
    date = True,
    commonDates = False,
    infoArticle = False,
    stories = False,
    socialScore = False,
    imageCount = 0)
  • title: return the title of the event
  • summary: return the summary of the event
  • articleCounts: return the number of articles that are assigned to the event
  • concepts: return information about the main concepts related to the event. Properties are set by ConceptInfoFlags().
  • categories: return information about the categories related to the event. Properties are set by CategoryInfoFlags().
  • location: return the location where the event occurred. Properties are set by CategoryInfoFlags().
  • date: return information about the date of the event
  • commonDates: return the dates that were commonly found in the articles about the event
  • infoArticle: return the article from which we have extracted the title and summary of the event
  • stories: return the list of stories (clusters) that are about the event. Properties are set by StoryInfoFlags().
  • socialScore: score computed based on how frequently the articles in the event were shared on social media
  • imageCount: number of images to be returned for an event

SourceInfoFlags

Specifies what information about a news source should be returned by the API call. The default constructor for SourceInfoFlags looks as follows:

SourceInfoFlags(title = True,
    description = False,
    location = False,
    ranking = False,
    image = False,
    articleCount = False,
    socialMedia = False)
  • title: the title of the news source
  • description: description of the news source
  • location: geographic location of the news source. Properties are set by LocationInfoFlags().
  • ranking: obtain various rankings of the news source
  • image: image and thumb image for the news source
  • articleCount: the number of articles from this news source that are stored in Event Registry
  • socialMedia: social media accounts for the news source

CategoryInfoFlags

Specifies what information about a category should be returned by the API call. The default constructor for CategoryInfoFlags looks as follows:

CategoryInfoFlags(trendingScore = False)
  • trendingScore: information about how the category is currently trending. The score is computed as Pearson residual by comparing the trending of the category in the last 2 days compared to the last 14 days

ConceptInfoFlags

Specifies what information about a concept should be returned by the API call. The default constructor for ConceptInfoFlags looks as follows:

ConceptInfoFlags(type = "concepts",
    lang = "eng",
    label = True,
    synonyms = False,
    image = False,
    description = False,
    conceptClassMembership = False,
    conceptClassMembershipFull = False,
    trendingScore = False)
  • type: which types of concepts should be provided in events, stories, ... Options: person, loc, org, wiki (non-entities), concepts (=person+loc+org+wiki), conceptClass, conceptFolder
  • lang: in which languages should be the labels for provided concepts
  • label: return label(s) of the concept
  • synonyms: return concept synonyms (if any)
  • image: provide an image associated with the concept
  • description: description of the concept
  • trendingScore: information about how the concept is currently trending. The score is computed as Pearson residual by comparing the trending of the concept in the last 2 days compared to the last 14 days

LocationInfoFlags

Specifies what information about a geographic location should be returned by the API call. Locations are sub-types of concepts so this information is always provided as a location property in concept information. country* flags are taken into account when the locations represent countries. Similarly place* flags are relevant when the location is a place (city, area, ...) The default constructor for LocationInfoFlags looks as follows:

LocationInfoFlags(label = True,
    wikiUri = False,
    geoNamesId = False,
    population = False,
    geoLocation = False,
    countryArea = False,
    countryDetails = False,
    countryContinent = False,
    placeFeatureCode = False,
    placeCountry = True)
  • label: return label of the place/country
  • wikiUri: return wiki url of the place/country
  • geoNamesId: return geonames id for the place/country
  • population: return the population of the place/country
  • geoLocation: return geographic coordinates of the place/country
  • countryArea: return geographic area of the country
  • countryContinent: return continent where the country is located
  • placeFeatureCode: return the geonames feature code of the place
  • placeCountry: return information about the country where the place is located

ConceptClassInfoFlags

Specifies what information about a concept class should be returned by the API call. The default constructor for ConceptClassInfoFlags looks as follows:

ConceptClassInfoFlags(parentLabels = True,
    concepts = False)
  • parentLabels: return the list of labels of the parent concept classes
  • concepts: return the list of concepts assigned to the concept class

ConceptFolderInfoFlags

Specifies what information about a concept folder should be returned by the API call. The default constructor for ConceptFolderInfoFlags looks as follows:

ConceptFolderInfoFlags(definition = False,
    owner = False)
  • definition: return the complete definition of the concept folder
  • owner: return information about the owner of the concept folder

StoryInfoFlags

Specifies what information about a story (cluster) should be returned by the API call. The default constructor for StoryInfoFlags looks as follows:

StoryInfoFlags(basicStats = True,
    location = True,
    date = False,
    title = False,
    summary = False,
    concepts = False,
    categories = False,
    medoidArticle = False,
    commonDates = False,
    socialScore = False,
    imageCount = 0)
  • basicStats: core stats about the story
  • location: the geographic location that the story is about. Properties are set by LocationInfoFlags().
  • date: date of the story
  • title: the title of the story
  • summary: summary of the story
  • concepts: return information about the main concepts related to the story. Properties are set by ConceptInfoFlags().
  • categories: categories associated with the story. Properties are set by CategoryInfoFlags().
  • medoidArticle: the article that is closest to the center of the cluster of articles assigned to the story. Properties are set by ArticleInfoFlags().
  • commonDates: dates that were frequently identified in the articles belonging to the story
  • socialScore: score computed based on how frequently the articles in the story were shared on social media
  • imageCount: number of images to be returned for a story

NewsAPI.ai

Home

Core Information
Usage tracking
Terminology
EventRegistry class
ReturnInfo class
Data models for returned information
Finding concepts for keywords
Filtering content by news sources

Text analytics
Semantic annotation, categorization, sentiment

Searching
Searching for events
Searching for articles

Article/event info
Get event information
Get article information

Other
Supported languages
Different ways to search using keywords
Feed of new articles/events
Social media shares
Daily trends
Find the event for your own text
Article URL to URI mapping

Clone this wiki locally