ReturnInfo class

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 are 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 = ConceptInfoFlags(),        # 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 = 300,
                 basicInfo = True, 
                 title = True,
                 body = True,
                 eventUri = True,
                 concepts = False,
                 storyUri = False,
                 duplicateList = False,
                 originalArticle = False,
                 categories = False,
                 location = False,
                 image = False,
                 extractedDates = False,
                 socialScore = False,
                 details = False)

• bodyLen: determines the maximum length of the article body (use -1 for full body, 0 for empty)
• basicInfo: core article information
• title: article title
• body: article body
• eventUri: uri of the event to which the article belongs
• concepts: the list of concepts mentioned in the article. Properties are set by ConceptInfoFlags().
• storyUri: uri of the story (cluster) to which the article belongs
• duplicateList: the list of articles that are a copy of this article. Properties are set by ArticleInfoFlags().
• originalArticle: if the article is a duplicate, this will provide information about the original article. Properties are set by ArticleInfoFlags().
• categories: the list of categories assigned to the article. Properties are set by CategoryInfoFlags().
• location: the geographic location that the event mentioned in the article is about. Properties are set by LocationInfoFlags().
• image: url to the image associated with the article
• extractedDates: the list of dates found mentioned in the article
• socialScore: information about the number of times the article was shared on Facebook and Twitter
• details: potential additional details

##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,
                 stories = False,
                 socialScore = False,
                 details = 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 occured. 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
• 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,
                 importance = False,
                 articleCount = False,
                 tags = False,
                 details = False)

• title: title of the news source
• description: description of the news source
• location: geographic location of the news source. Properties are set by LocationInfoFlags().
• importance: a score of importance assigned to the news source
• articleCount: the number of articles from this news source that are stored in Event Registry
• tags: custom tags assigned to 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(parentUri = False,
                 childrenUris = False,
                 trendingScore = False,
                 trendingHistory = False,
                 details = False,
                 trendingSource = "news")

• parentUri: uri of the parent category
• childrenUris: the list of category uris that are children of the category
• trendingScore: information about how the category is currently trending. The score is computed as Pearson residual by comparing the trending of the category in last 2 days compared to last 14 days
• trendingHistory: information about the number of times articles were assigned to the category in last 30 days
• trendingSource: source of information to be used when computing the trending score for a category. Relevant only if CategoryInfoFlags.trendingScore == True or CategoryInfoFlags.trendingHistory == True. Valid options: news, social

##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,
                 details = False,
                 conceptClassMembership = False,
                 conceptClassMembershipFull = False,
                 conceptFolderMembership = False,
                 trendingScore = False,
                 trendingHistory = False,
                 trendingSource = "news")

• 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
• conceptClassMembership: provide a list of concept classes where the concept is a member
• conceptClassMembership: provide a list of concept classes and their parents where the concept is a member
• conceptFolderMembership: provide a list of publicly visible concept folders where the concept is a member
• trendingScore: information about how the concept is currently trending. The score is computed as Pearson residual by comparing the trending of the concept in last 2 days compared to last 14 days
• trendingHistory: information about the number of times articles were assigned to the concept in last 30 days
• trendingSource: source of information to be used when computing the trending score for a concept. Relevant only if ConceptInfoFlags.trendingScore == True or ConceptInfoFlags.trendingHistory == True. Valid options: news, social

##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,
                 details = False)

• parentLabels: return the list of labels of the parent concept classes
• concepts: return the list of concepts assigned to the concept class
• details: return additional details about 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,
                 details = False)

• definition: return the complete definition of the concept folder
• owner: return information about the owner of the concept folder
• details: return additional details about 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,
                 categories = False,
                 date = False,
                 concepts = False,
                 title = False,
                 summary = False,
                 medoidArticle = False,
                 commonDates = False,
                 socialScore = False,
                 details = False,
                 imageCount = 0)

• basicStats: core stats about the story
• location: geographic location that the story is about. Properties are set by LocationInfoFlags().
• categories: categories associated with the story. Properties are set by CategoryInfoFlags().
• date: date of the story
• concepts: return information about the main concepts related to the story. Properties are set by ConceptInfoFlags().
• title: title of the story
• summary: summary of the story
• 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