pynytimes
Search
K

Article Search

Find articles that match search criteria.

Usage

NYTAPI.article_search(query=None, dates=None, options=None, results=10)

Parameters

Variables
Description
Data type
Required
query
What you want to search for
str
False
results
The amount of results that you want to receive (returns a multiple of 10)
int
False
dates
A dictionary of the dates you'd like the results to be between
dict
False
options
A dictionary of additional options
dict
False

dates

Variables
Description
Data type
Required
begin
Results should be published at or after this date
datetime.datetime or datetime.date
False
end
Results should be published at or before this date
datetime.datetime or datetime.date
False

options

Variables
Description
Data type
Required
sort
How you want the results to be sorted (oldest, newest or relevance)
str
False
sources
Results should be from one of these sources
list
False
news_desk
Results should be from one of these news desks (valid options)
list
False
type_of_material
Results should be from this type of material (valid options)
list
False
section_name
Results should be from this section (valid options)
list
False
subject
Results should contain at least one of these keywords
list
False
body
Results should contain at least one of the strings in the list in the article text
list
False
headline
Results should contain at least one of the strings in the headline
list
False
fq
str
False

Example

import datetime
articles = nyt.article_search(
query = "Obama", # Search for articles about Obama
results = 30, # Return 30 articles
# Search for articles in January and February 2019
dates = {
"begin": datetime.datetime(2019, 1, 31),
"end": datetime.datetime(2019, 2, 28)
},
options = {
"sort": "oldest", # Sort by oldest options
# Return articles from the following four sources
"sources": [
"New York Times",
"AP",
"Reuters",
"International Herald Tribune"
],
# Only get information from the Politics desk
"news_desk": [
"Politics"
],
# Only return News Analyses
"type_of_material": [
"News Analysis"
],
# The article text should contain either the word
# "Obamacare" or "healthcare"
"body": [
"Obamacare",
"healthcare"
],
# Headline should contain "bill", "costs over", or "victory"
"headline": [
"bill",
"costs over",
"victory"
]
}
)

Advanced Usage: Filter Queries

The New York Times article search API allows for many more filters, which can be combined much more specifically. You can specify a filter query be specifying the fq key of the options parameter. This can be done as follows:
# Get all sports articles from New York City
articles = nyt.article_search(options={
"fq": "news_desk:("Sports") AND glocations:(\"NEW YORK CITY\")"
})
# Get all articles about Obama, but exclude all
# articles from New York City
articles = nyt.article_search(options={
"fq": "Obama AND -glocations:(\"NEW YORK CITY\")"
})
To learn more about all the possibilities of the advanced filter queries, you can visit the New York Times Developer API reference.