ReturnInfo class

Whenever you will be making a request to Event Registry, you will be getting back a JSON object containing information about articles, events, concepts, categories and/or other types of data. Event Registry can return you various properties for each of this type. To reduce the size of the responses, only some of the properties are sent by default. In cases when you want to get more/less properties, you can modify the ReturnInfo instance that is specified in most of the requests.

ReturnInfo is just a wrapper for individual data types and the properties that should be returned for them. ReturnInfo constructor 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 types, the default flags are set to return the most common set of parameters. In most cases you will not need to modify them. Also 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 nowhere in your output you will get any event.

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

##ArticleInfoFlags

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
• storyUri: uri of the story (cluster) to which the article belongs
• duplicateList: the list of articles that are a copy of this article
• originalArticle: if the article is a duplicate, this will provide information about the original article
• categories: the list of categories assigned to the article
• location: the geographic location that the event mentioned in the article is about
• 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

##StoryInfoFlags

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
• categories: categories associated with the story
• 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
• 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

##EventInfoFlags

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
• categories: return information about the categories related to the event
• location: return the location where the event occured
• 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
• 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

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
• 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

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

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

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

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

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