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
​Advanced usage: implement your own filter query​
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.

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

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

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`	Advanced usage: implement your own filter query	`str`	False

Last modified 5mo ago

Article Search

Usage

Parameters

`dates`

`options`

Example

Advanced Usage: Filter Queries