Get events
Find events that match one or more search conditions.
The search conditions can be specifying by setting one or multiple search parameters, such as
keyword, conceptUri, sourceUri, categoryUri, dateStart, etc.
If you need to specify a complex query with nested conditions that use a combination of Boolean AND, OR and NOT operators, then best approach is to specify the query parameter.
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 matching events (default) or one of the various aggregates (summaries) of the matching events. In case of the aggregates, for example, the returned data can contain the geographic locations, where the events matching criteria occured, date of the matching events, etc.
Each search can return up to 50 events per call. If the query matches more than 50 events, you can retrieve them by using
eventsPage parameter and setting it to value 2, 3, 4, etc to retrieve additional pages of results.
Each call will count as one event action (regardless of the number of returned events).
Click to see different parameters that you can specify in order to filter the events
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 the query parameters specified directly (keyword, conceptUri, sourceUri, categoryUri, etc) will be ignored.
Find events in which news articles mention the specified keyword or a phrase.
If you specify multiple keyword parameters, then only events with articles 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.
Barack Obama
Find events for which the concept with concept uri is important.
You can specify up to 50 concepts in a single search.
If multiple conceptUri parameters are provided, then only events 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.
http://en.wikipedia.org/wiki/World_Health_Organization
Find events that are about a particular category.
You can specify up to 20 categories in a single search.
If multiple categoryUri parameters are provided, then events 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.
dmoz/Business/AccountingFind events that contain one or more articles that have been written by a specific news source. Check autosuggest methods to get value for a source name.
bbc.co.ukFind events that contain one or more articles by news sources located at the given geographic location (city or a country). Check autosuggest methods to get value for a location name.
http://en.wikipedia.org/wiki/GermanyFind events that contain one or more articles by news sources that are assigned to the predefined group of news sources.
general/ERtop10Find events that contain articles that were written by a particular author. Check autosuggest methods to get value for author uri based on the author name (and potentially source url).
mark_mazzetti@nytimes.comFind events that occurred at a particular geographic location. Check autosuggest methods to get URI value for a given location name.
http://en.wikipedia.org/wiki/United_StatesFind events that contain articles in the specified language(s). You can specify at most 5 languages in a single search. Specify languages using their ISO3 language codes. The full list of languages and their ISO3 codes can be found on this page.
engLimit the events to those that occured on or after this date. The date of the event is extracted from the news articles about the event and are potentially quite different than the dates when the articles about the event were published. The date should be in the YYYY-MM-DD format.
2018-01-03Limit the events to those that occured before or on this date. The date of the event is extracted from the news articles about the event and are potentially quite different than the dates when the articles about the event were published. The date should be in the YYYY-MM-DD format.
2018-01-10The minimum value of the sentiment, the event 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 events covered in English, since the sentiment can only be computed for English language.
The maximum value of the sentiment, the event 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 events covered in English, since the sentiment can only be computed for English language.
Find events that have been reported in at least minArticlesInEvent articles (regardless of language).
Find events that have not been reported in more than maxArticlesInEvent articles (regardless of language)
Limit the events to those for which the reporting date was on or after this date. The reporting date is computed by analyzing all the dates when the articles about an event were published and computing the average value. The date should be in the YYYY-MM-DD format.
2018-01-03Limit the events to those for which the reporting date was before or on this date. The reporting date is computed by analyzing all the dates when the articles about an event were published and computing the average value. The date should be in the YYYY-MM-DD format.
2018-01-10
Find events that contain one or more articles that explicitly mention a date that is equal or greater than dateMentionStart.
The date should be in the YYYY-MM-DD format.
2018-01-10
Find events that contain one or more articles that explicitly mention a date that is lower or equal to dateMentionEnd.
The date should be in the YYYY-MM-DD format.
2018-01-10
What data should be used when searching using the keywords provided by keywords parameter.
body, title, title,bodybody
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 article about an event; if or then an event will be returned if it's articles mentions any of the provided keywords.
and, orand
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.
phrase, exact, simplephrase
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 event; if or then an event will be returned if it mentions any of the provided concepts.
and, orand
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 event; if or then an event will be returned if it mentions any of the provided categories.
and, oror
Ignore events in which news articles mention the specified keyword or phrase.
If you specify multiple ignoreKeyword parameters, then events with articles that mention any of these keywords will be ignored.
Donald Trump
Ignore events for which the concept with concept uri is important.
You can specify up to 50 concepts in a single search.
If you specify multiple ignoreConceptUri parameters, then events that mention any of them will be ignored.
Check autosuggest methods to get value for a specified concept label.
http://en.wikipedia.org/wiki/World_Health_Organization
Ignore events that are about a particular category.
You can specify up to 20 categories in a single search.
If you specify multiple ignoreCategoryUri parameters, then events that mention any of them will be ignored.
Check autosuggest methods to get value for a specified category name.
dmoz/Business/AccountingIgnore events that contain one or more articles that have been written by a news source. Check autosuggest methods to get value for a source name.
bbc.co.ukIgnore events that contain one or more articles by news sources located at the given geographic location (city or a country). Check autosuggest methods to get value for a location name.
bbc.co.ukIgnore events that contain one or more articles by news sources that are assigned to the specified group of news sources.
general/ERtop10Ignore events that contain articles, which were written by a particular author. Check autosuggest methods to get value for author uri based on the author name (and potentially source url).
mark_mazzetti@nytimes.comIgnore events that occurred at a particular geographic location. Check autosuggest methods to get URI value for a given location name.
http://en.wikipedia.org/wiki/United_StatesIgnore events that contain articles in the specified language(s). You can specify at most 5 languages in a single search. Specify languages using their ISO3 language codes. The full list of languages and their ISO3 codes can be found on this page.
deu
What data should be used when searching using the keywords provided by ignoreKeywords parameter.
body, title, title,bodyThe API call can return more or less meta-data information about the events, articles, concepts, categories, sources and locations. Click to see the available properties that can be specified to determine the amount of returned information.
Set this parameter to true to include the event title in the response.
trueSet this parameter to true to include the event title in the response.
falseSet this parameter to true to include the event social score in the response.
falseSet this parameter to true to include the event sentiment in the response.
trueSet this parameter to true to include the event location in the response.
trueSet this parameter to true to include the event date in the response.
trueSet this parameter to true to include the article counts for events in the response.
trueSet this parameter to true to include the event concepts in the response.
trueSet this parameter to true to include the event categories in the response.
trueSet this parameter to true to include the event commmon dates in the response.
falseSet this parameter to true to include the event stories in the response.
falseDefine how many images you would like to have in the response.
0Set this parameter to true to include the concept label in the response.
trueSet this parameter to true to include the concept image in the response.
falseSet this parameter to true to include the concept synonyms in the response.
falseDefine the language of the concept label.
engSet this parameter to true to include story basic stats in the response.
falseSet this parameter to true to include the story title in the response.
falseSet this parameter to true to include the story location in the response.
falseSet this parameter to true to include the story date in the response.
falseSet this parameter to true to include the story concepts in the response.
falseSet this parameter to true to include the story categories in the response.
falseSet this parameter to true to include story medoid article in the response.
falseSet this parameter to true to include story common dates in the response.
falseDefine how many images you would like to have in the response.
0Set this parameter to true to include category parent uri in the response.
falseSet to true to include the population size of the location.
falseSet to true to include the GeoNames id of the location.
falseSet to true to include the are of the location in squared km.
falseSet to true to get the continent of the country for location objects.
false