Introduction
API endpoints
Annotate Named entity recognition Categorize Semantic similarity Sentiment Extract article information Detect language
Get articles Get articles for topic page Get article details Stream of new articles
Get events Get events for a topic page Get event details Stream of events Get list of breaking events
Get mentions
Suggest concepts Suggest categories Suggest sources Suggest authors Suggest locations Suggest event types
API Usage
Reference
Terminology
Supported languages
Response format
Building queries
Search query language
Keyword search modes
Integrations
MCP Integration
OverviewExample 1Example 2Example 3

Get mentions

Try in sandbox  

Obtain sentences from news articles that mention a certain relation of interest.

This endpoint can be used to obtain specific sentences from news articles that describe a particular relation of interest, such as a merger between companies, layoffs, a product release, a natural disaster, etc. There is a taxonomy of over 100 relations that we are able to identify and we call these relations event types.

Each object that we return in this API endpoint is called a mention and contains multiple properties like the sentence mentioning the event type, sentiment, source information, list of mentioned entities, categories, link to the original article and more.

The search conditions can be specified by setting the query parameter, or by specifying one or multiple search parameters, such as eventTypeUri, conceptUri, sdgUri, etc. To remove some of the results matching the positive conditions, you can specify some negative conditions using ignoreKeyword, ignoreSourceUri, and other ignore* parameters.

The results of the search can be the list of sentences with details (called mentions) matching the conditions (default) or one of the various aggregates (summaries) of the matching results. These aggregates can include information like when the articles with those sentences were published, which are the top sources publishing the results, the sentiment distribution, category distribution, etc.

Each search can return up to 100 mentions per call. If the query matches more than 100 mentions, you can retrieve them by using mentionsPage parameter and setting it to value 2, 3, 4, etc to retrieve additional pages of results. Each call will count as one search action.

Endpointhttps://eventregistry.org/api/v1/eventType/mention/getMentions
HeadersContent-Type: application/json

Find mentions of stock-price-change event types related to companies in the transportation industry that occured in April 2023.

Repeat the query multiple times and increase the mentionsPage parameter, to retrieve more results.

Request body

Parameters 
apiKey  string (required)

Your API key

resultType  string

Define what kind of results of the search you would like to get.

Available values:  mentions, uriWgtList, langAggr, timeAggr, sourceAggr, sourceExAggr, keywordAggr, locAggr, locTimeAggr, conceptAggr, eventTypeAggr, categoryAggr, sentimentAggr, recentActivityMentions
Default value:  mentions
mentionsPage  integer

Determines the page of the results to return (starting from 1). Relevant when resultType = mentions.

Default value:  1
mentionsCount  integer

Define how many mentions (up to 100) will be returned. Relevant when resultType = mentions.

Default value:  100
mentionsSortBy  string

Choose the criteria for sorting the returned mentions. rel (relevance to the query), date (publishing date), sourceImportance (manually curated score of source importance - high value, high importance), sourceImportanceRank (reverse of sourceImportance), sourceAlexaGlobalRank (global rank of the news source), or sourceAlexaCountryRank (country rank of the news source). Relevant when resultType = mentions.

Available values:  date, rel, sourceImportance, sourceAlexaGlobalRank, sourceAlexaCountryRank
Default value:  date
mentionsSortByAsc  boolean

Should the results be ordered in ascending order or descending order (default). Relevant when resultType = mentions.

Default value:  false
Filters 

Click to see different parameters that you can specify in order to filter the mentions

query  object

Query object with one or more search conditions. The query object should match the Advanced Query Language format. If you specify the query parameter, then other query parameters like keyword, conceptUri, sourceUri, etc. should not be specified.

keyword  string | string[]

Find sentences that mention the specified keyword or a phrase. You can specify at most 60 keywords in a single search. If you specify multiple keyword parameters, then only sentences that mention all of them will be returned, unless you specify keywordOper parameter and set it to or. Use the keywordSearchMode parameter to control how the keyword is matched; see the keyword search modes section.

Example value:  Barack Obama
conceptUri  string | string[]

Find sentences that mention the concept with a concept uri. You can specify at most 50 concepts in a single search. If multiple conceptUri parameters are provided, then only sentences that are about all specified concepts will be returned, unless you specify conceptOper parameter and set it to or. Check autosuggest methods to get concept URI value for a specified concept label.

Example value:  http://en.wikipedia.org/wiki/World_Health_Organization
eventTypeUri  string | string[]

Find sentences that are marked as belonging to a particular event type. If multiple eventTypeUri parameters are provided, then sentences that are about any of the specified event types will be returned. Check autosuggest methods to get event type URI value for a specified event type name.

Example value:  et/business/acquisitions-mergers/acquisition/approved
industryUri  string | string[]

Find sentences that mention a company that is in a certain industry. If multiple industryUri parameters are provided, then sentences that are about a company from any of the specified industries will be returned. Check autosuggest methods to get industry URI value for a specified industry name.

Example value:  sectors/Communications
sdgUri  string | string[]

Find sentences that mention an event type that belongs to a certain SDG (Sustainable Development Goal). If multiple sdgUri parameters are provided, then sentences that are about any of the specified SDGs will be returned.

Example value:  sdg/sdg5_gender_equality
sasbUri  string | string[]

Find sentences that mention an event type that belongs to a certain SASB Materiality Map. If multiple sasbUri parameters are provided, then sentences that are about any of the specified SASB will be returned.

Example value:  sasb/environment/air_quality
esgUri  string | string[]

Find sentences that mention an event type that belongs to a certain ESG (Environmental, social, and governance). If multiple esgUri parameters are provided, then sentences that are about any of the specified ESGs will be returned.

Example value:  esg/environment
categoryUri  string | string[]

Find sentences that are assigned to a particular category. You can specify at most 20 categories in a single search. If multiple categoryUri parameters are provided, then sentences that are about any of the specified categories will be returned, unless you specify categoryOper parameter and set it to and. Check autosuggest methods to get value for a specified category name.

Example value:  dmoz/Business/Accounting
sourceUri  string | string[]

Find sentences that have been published in articles by a news source. If you specify multiple sourceUri parameters, then mentions from any of the specified sources will be returned. Check autosuggest methods to get value for a source name.

Example value:  bbc.co.uk
sourceLocationUri  string | string[]

Find sentences that were published in articles by news sources located at the given geographic location (city or country). If you specify multiple sourceLocationUri parameters, then sentences from sources from any of the specified sources will be returned. Check autosuggest methods to get value for a location name.

Example value:  http://en.wikipedia.org/wiki/Germany
sourceGroupUri  string | string[]

Find sentences that were published in articles by news sources that are assigned to some predefined group of news sources.

Example value:  general/ERtop10
locationUri  string | string[]

Find sentences that describe something that occured at a particular location (based on the location mentioned in the article dateline). Check autosuggest methods to get value for a location name.

Example value:  http://en.wikipedia.org/wiki/United_States
dateStart  string

The starting date on or after the articles mentioning the sentences of interest were published. The date should be in the YYYY-MM-DD format.

Example value:  2018-01-03
dateEnd  string

The last date on which the articles mentioning the sentences of interest were published. The date should be in the YYYY-MM-DD format.

Example value:  2018-01-10
factLevel  string | string[]

How factual should be the sentence?

Available values:  fact, opinion, forecast
keywordOper  string

If more keywords are provided with the keyword parameter, what should be the Boolean operator used. If and (default) then all of the specified keywords have to be present in the sentence; if or then a sentence will be returned if it mentions any of the provided keywords.

Available values:  and, or
Default value:  and
keywordSearchMode  string

Determines how the keywords provided with the keyword parameter are matched against the content. Use phrase (default) to match the keyword as an exact phrase, exact to use the Boolean query language (with AND, OR, NOT, NEAR and NEXT operators), or simple for a relevance-based search that does not require all terms to be present. See the keyword search modes section for details and examples.

Available values:  phrase, exact, simple
Default value:  phrase
conceptOper  string

If more concepts are provided with the conceptUri parameter, what should be the Boolean operator used. If and (default) then all of the specified concepts have to be present in the sentence; if or then an sentence will be returned if it mentions any of the provided concepts.

Available values:  and, or
Default value:  and
categoryOper  string

If more categories are provided with the categoryUri parameter, what should be the Boolean operator used. If and then all of the specified categories have to be present in the sentence; if or then an sentence will be returned if it mentions any of the provided categories.

Available values:  and, or
Default value:  or
ignoreEventTypeUri  string | string[]

Ignore sentences that are marked as belonging to a particular event type. If multiple eventTypeUri parameters are provided, then sentences that are about any of the specified event types will be returned. Check autosuggest methods to get event type URI value for a specified event type name.

Example value:  et/business/acquisitions-mergers/acquisition/approved
ignoreIndustryUri  string | string[]

Ignore sentences that mention a company that is in a certain industry. If multiple industryUri parameters are provided, then sentences that are about a company from any of the specified industries will be returned. Check autosuggest methods to get industry URI value for a specified industry name.

Example value:  sectors/Communications
ignoreSdgUri  string | string[]

Ignore sentences that mention an event type that belongs to a certain SDG (Sustainable Development Goal). If multiple sdgUri parameters are provided, then sentences that are about any of the specified SDGs will be returned.

Example value:  sdg/sdg5_gender_equality
ignoreSasbUri  string | string[]

Ignore sentences that mention an event type that belongs to a certain SASB Materiality Map. If multiple sasbUri parameters are provided, then sentences that are about any of the specified SASB will be returned.

Example value:  sasb/environment/air_quality
ignoreEsgUri  string | string[]

Ignore sentences that mention an event type that belongs to a certain ESG (Environmental, social, and governance). If multiple esgUri parameters are provided, then sentences that are about any of the specified ESGs will be returned.

Example value:  esg/environment
ignoreKeyword  string | string[]

Ignore sentences that mention the specified keyword or phrase. You can specify at most 60 keywords in a single search. If you specify multiple ignoreKeyword parameters, then sentences that mention any of these keywords will be ignored.

Example value:  Donald Trump
ignoreConceptUri  string | string[]

Ignore sentences that mention the concept with concept uri. You can specify at most 50 concepts in a single search. If you specify multiple ignoreConceptUri parameters then sentences that mention any of them will be ignored. Check autosuggest methods to get value for a specified concept label.

Example value:  http://en.wikipedia.org/wiki/World_Health_Organization
ignoreCategoryUri  string | string[]

Ignore sentences that are assigned into a particular category. You can specify at most 20 categories in a single search. If you specify multiple ignoreCategoryUri parameters then sentences that mention any of them will be ignored. Check autosuggest methods to get value for a specified category name.

Example value:  dmoz/Business/Accounting
ignoreSourceUri  string | string[]

Ignore sentences that have been published in articles by a news source. If you specify multiple ignoreSourceUri parameters, then sentences from any of the specified sources will be ignored. Check autosuggest methods to get value for a source name.

Example value:  bbc.co.uk
ignoreSourceLocationUri  string | string[]

Ignore sentences that were published by news sources located at the given geographic location (city or country). If you specify multiple ignoreSourceLocationUri parameters, then sentences from sources from any of the specified sources will be ignored. Check autosuggest methods to get value for a location name.

Example value:  http://en.wikipedia.org/wiki/Olsberg,_Germany
ignoreSourceGroupUri  string | string[]

Ignore sentences that were published by news sources that are assigned to some predefined group of news sources.

Example value:  general/ERtop10
ignoreLocationUri  string | string[]

Ignore sentences that describe something that occured at a particular location (based on the location mentioned in the dateline). Check autosuggest methods to get value for a location name.

Example value:  http://en.wikipedia.org/wiki/United_States
startSourceRankPercentile  integer

Starting ranking percentile of the sources to consider in the results (default: 0). Value should be in range 0-90 and divisible by 10.

Default value:  0
endSourceRankPercentile  integer

Ending ranking percentile of the sources to consider in the results (default: 100). Value should be in range 10-100 and divisible by 10.

Default value:  100
minSentiment  integer

The minimum value of the sentiment, the article should have. Valid value is any floating number between -1 (very negative) to 1 (very positive). 0 represents neutral sentiment. Note that setting the value will automatically reduce results to just English articles, since the sentiment can only be computed for English language.

maxSentiment  integer

The maximum value of the sentiment, the article should have. Valid value is any floating number between -1 (very negative) to 1 (very positive). 0 represents neutral sentiment. Note that setting the value will automatically reduce results to just English articles, since the sentiment can only be computed for English language.

minSentenceIndex  integer

Articles are split into sentences. What is the minimum index of the sentence in the article for it to be included in the results? Title counts as index 0, first sentence in the body counts as 1, etc.

maxSentenceIndex  integer

Articles are split into sentences. What is the maximum index of the sentence in the article for it to be included in the results? Title counts as index 0, first sentence in the body counts as 1, etc. If the results should only be either from the title or the first sentence of the body, then set this parameter to 1.

showDuplicates  boolean

Some sentences can be duplicates of other sentences (very similar or identical). Should we return the duplicates to the client?

Default value:  false
Returned Details 

The API call can return more or less meta-data information about the mention, concepts, categories, sources and locations. Click to see the available properties that can be specified to determine the amount of returned information.

includeMentionBasicInfo  boolean

Return the basic information about the mention (language, date, time).

Default value:  true
includeMentionSlots  boolean

Return the information about the entities mentioned in the sentence

Default value:  false
includeMentionCategories  boolean

Return the list of categories associated with the article in which the sentence appeared.

Default value:  false
includeMentionFrameworks  boolean

Return the SDG, ESG and SASB frameworks associated with the event type.

Default value:  false
includeSourceTitle  boolean

Set this parameter to true to include the source title in the response.

Default value:  true
includeSourceLocation  boolean

Set this parameter to true to include the source location in the response.

Default value:  false
includeConceptSynonyms  boolean

Set this parameter to true to include the concept synonyms in the response.

Default value:  false
conceptLang  string

Define the language of the concept label.

Default value:  eng
includeLocationGeoLocation  boolean

Set to true to include the geo location (latitude, longitude) for items that are locations.

Default value:  false