Get articles
Find news articles 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 articles (default) or one of the various aggregates (summaries) of the matching articles. These aggregates can include information like when the articles were published, which are the top sources publishing resulting articles, the sentiment distribution, category distribution, etc.
Each search can return up to 100 articles per call. If the query matches more than 100 articles, you can retrieve them by using
articlesPage parameter and setting it to value 2, 3, 4, etc to retrieve additional pages of results.
Each call will count as one search action (regardless of the number of returned articles).
Click to see different parameters that you can specify in order to filter the articles
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.
Find articles 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 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 articles 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 articles 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 articles 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 articles 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/Accounting
Find articles that have been published by a news source.
If you specify multiple sourceUri parameters, then articles from any of the specified sources will be returned.
Check autosuggest methods to get value for a source name.
bbc.co.uk
Find articles that were published by news sources located at the given geographic location (city or country).
If you specify multiple sourceLocationUri parameters, then articles from sources from any of the specified sources will be returned.
Check autosuggest methods to get value for a location name.
http://en.wikipedia.org/wiki/GermanyFind articles that were published by news sources that are assigned to some predefined group of news sources.
general/ERtop10Find 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.com
Find articles 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. NOTE: If
a location will not be specified in the dateline (immediate start of the article), the article will not be returned. Consider also using
conceptUri to find articles that mention a particular location.
http://en.wikipedia.org/wiki/United_StatesFind articles in the specified language(s). If parameter is not set, articles in all languages will be included. 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.
engThe starting date on or after the articles of interest were published. The date should be in the YYYY-MM-DD format.
2018-01-03The last date on which the articles of interest were published. The date should be in the YYYY-MM-DD format.
2018-01-10
Find 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 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; if or then an article will be returned if it 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 article; if or then an article 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 article; if or then an article will be returned if it mentions any of the provided categories.
and, oror
Ignore articles 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 articles that mention any of these keywords will be ignored.
Donald Trump
Ignore articles 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 articles 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 articles 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 articles that mention any of them will be ignored.
Check autosuggest methods to get value for a specified category name.
dmoz/Business/Accounting
Ignore articles that have been published by a news source.
If you specify multiple ignoreSourceUri parameters, then articles from any of the specified sources will be ignored.
Check autosuggest methods to get value for a source name.
bbc.co.uk
Ignore articles that were published by news sources located at the given geographic location (city or country).
If you specify multiple ignoreSourceLocationUri parameters, then articles from sources from any of the specified sources will be ignored.
Check autosuggest methods to get value for a location name.
http://en.wikipedia.org/wiki/Olsberg,_GermanyIgnore articles that were published by news sources that are assigned to some predefined group of news sources.
general/ERtop10Ignore articles 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.
http://en.wikipedia.org/wiki/United_StatesIgnore 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.comIgnore 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.
deuWhat data should be used when searching using the keywords provided by ignoreKeywords parameter.
body, title, title,bodybodyStarting ranking percentile of the sources to consider in the results (default: 0). Value should be in range 0-90 and divisible by 10.
0Ending ranking percentile of the sources to consider in the results (default: 100). Value should be in range 10-100 and divisible by 10.
100The 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.
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.
Some articles can be duplicates of other articles. What should be done with them.
skipDuplicates, keepOnlyDuplicates, keepAllkeepAllSome articles describe a known event and some don't. This filter allows you to filter the resulting articles based on this criteria.
skipArticlesWithoutEvent, keepOnlyArticlesWithoutEvent, keepAllkeepAllThe API call can return more or less meta-data information about the 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 article title in the response.
trueSet this parameter to true to include the core article information in the response.
trueSet this parameter to true to include the article body in the response.
trueSet this parameter to true to include the uri of the event (to which the article belongs) in the response.
trueSet this parameter to true to include the information about how many times the article was shared on different social media.
falseSet this parameter to true to include the article sentiment in the response (value will be non-null only for English articles).
trueSet this parameter to true to include the article concepts in the response.
falseSet this parameter to true to include the article categories in the response.
falseSet this parameter to true to include the article location in the response.
falseSet this parameter to true to include the article image in the response.
trueSet this parameter to true to include the article authors in the response.
trueSet this parameter to true to include the article videos in the response.
falseSet this parameter to true to include the article links in the response.
falseSet this parameter to true to include article extracted dates in the response.
falseSet this parameter to true to include the list of duplicate articles in the response.
falseSet this parameter to true to include the original article in the response.
falseSet this parameter to true to include the source title in the response.
trueSet this parameter to true to include the source description in the response.
falseSet this parameter to true to include the source location in the response.
falseSet this parameter to true to include the source ranking in the response.
falseSet 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 category parent uri in the response.
falseSet to true to include the geo location (latitude, longitude) for items that are locations.
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