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:

new ReturnInfo({
    articleInfo = new ArticleInfoFlags(),             # details about the articles to return
    eventInfo = new EventInfoFlags(),                 # details about the events to return
    sourceInfo = new SourceInfoFlags(),               # details about the news sources to return
    categoryInfo = new CategoryInfoFlags(),           # details about the categories to return
    conceptInfo = new ConceptInfoFlags(),             # details about the concepts to return
    locationInfo = new LocationInfoFlags(),           # details about the locations to return
    storyInfo = new StoryInfoFlags(),                 # details about the stories to return
    conceptClassInfo = new ConceptInfoFlags(),        # details about the concept classes to return
    conceptFolderInfo = new 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:

new ArticleInfoFlags({
    bodyLen = -1,
    basicInfo = true,
    title = true,
    body = true,
    eventUri = true,
    concepts = false,
    storyUri = false,
    duplicateList = false,
    originalArticle = false,
    categories = false,
    location = false,
    image = false,
    extractedDates = false,
    shares = false,
    details = 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
• eventUri: uri of the event to which the article belongs
• concepts: the list of concepts mentioned in the article. Properties are set by new 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 new ArticleInfoFlags().
• originalArticle: if the article is a duplicate, this will provide information about the original article. Properties are set by new ArticleInfoFlags().
• categories: the list of categories assigned to the article. Properties are set by new CategoryInfoFlags().
• location: the geographic location that the event mentioned in the article is about. Properties are set by new LocationInfoFlags().
• image: url to the image associated with the article
• extractedDates: the list of dates found mentioned in the article
• shares: information about the number of times the article was shared on different social media
• 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:

new 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 new ConceptInfoFlags().
• categories: return information about the categories related to the event. Properties are set by new CategoryInfoFlags().
• location: return the location where the event occurred. Properties are set by new 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 new 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:

new SourceInfoFlags({
    title = true,
    description = false,
    location = false,
    ranking = false,
    image = false,
    articleCount = false,
    sourceGroups = 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 new 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
• sourceGroups: source groups to which the source belongs

CategoryInfoFlags

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

new 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:

new ConceptInfoFlags({
    type = "concepts",
    lang = "eng",
    label = true,
    synonyms = false,
    image = false,
    description = false,
    details = false,
    conceptClassMembership = false,
    conceptClassMembershipFull = 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
• conceptClassMembershipFull: provide a list of concept classes and their parents 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:

new 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:

new 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:

new 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:

new 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 new LocationInfoFlags().
• categories: categories associated with the story. Properties are set by new CategoryInfoFlags().
• date: date of the story
• concepts: return information about the main concepts related to the story. Properties are set by new 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 new 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