Use all (actually most) New York Times APIs, get all the data you need from the Times!

Extensive documentation is available at: https://pynytimes.michadenheijer.com/.

There are multiple options to install and ugprade pynytimes, but the easiest is by just installing it using pip (or pip3).

pip install --upgrade pynytimes

python -m pip install --upgrade pynytimes

You can easily import this library using:

from pynytimes import NYTAPI

Then you can simply add your API key (get your API key from The New York Times Dev Portal):

nyt = NYTAPI("Your API key", parse_dates=True)

Make sure that if you commit your code to GitHub you don't accidentially commit your API key.

When you have imported this library you can use the following features from the New York Times API.

Search

• Article search
• Book reviews
• Movie reviews

Popular

• Top stories
• Most viewed articles
• Most shared articles
• Best sellers lists

Metadata

• Article metadata
• Archive metadata
• Load latest articles

Other

• Tag query (TimesTags)

To get the current top stories use:

top_stories = nyt.top_stories()

Read the documentation to find the top stories per section.

You can also get todays most viewed articles:

most_viewed = nyt.most_viewed()

Read the documentation to get the most viewed articles per week or month.

To get the most shared articles (shared over email) use:

most_shared = nyt.most_shared()

Read the documentation to get the most shared articles using facebook.

Search articles using a query using:

articles = nyt.article_search(query="Obama")

In this example we have just defined the content of the search query (Obama), but we can add many more search parameters. Read the documentation to see how.

You can easily find book reviews for every book you've read. You can find those reviews by searching for the author, ISBN or title of the book.

# Get reviews by author (first and last name)
reviews = nyt.book_reviews(author="George Orwell")

# Get reviews by ISBN
reviews = nyt.book_reviews(isbn="9780062963673")

# Get book reviews by title
reviews = nyt.book_reviews(title="Becoming")

Read the documentation to find more information about additional parameters.

You can not only get the book reviews, but the movie reviews too.

reviews = nyt.movie_reviews(keyword="Green Book")

Read the documentation to find more information about additional parameters.

The New York Times has multiple best sellers lists. To get from the fiction best seller list:

# Get fiction best sellers list
books = nyt.best_sellers_list()

Read how to get the other best seller lists in the documentation.

With an URL from a New York Times article you can easily get all the metadata you need from it.

metadata = nyt.article_metadata(
    url = "https://www.nytimes.com/2019/10/20/world/middleeast/erdogan-turkey-nuclear-weapons-trump.html"
)

Read additional parameters in the documentation.

You can easily load the latest articles published by the New York Times.

latest = nyt.latest_articles(
    source = "nyt",
    section = "books"
)

Additional parameters can be found in the documentation.

The New York Times has their own tags library. You can query this library with this API.

tags = nyt.tag_query(
    "pentagon",
    max_results = 20
)

Additional parameters can be found in the documentation.

If you want to load all the metadata from a specific month, then this API makes that possible. Be aware you'll download a big JSON file (about 20 Mb), so it can take a while.

import datetime

data = nyt.archive_metadata(
    date = datetime.datetime(2019, 1, 1)
)

Read more in the documentation.

If you use pynytimes, a citation would be very much appriciated. If you're using BibTeX you can use the following citation:

@software{Den_Heijer_pynytimes_2023,
    author = {Den Heijer, Micha},
    license = {MIT},
    title = {{pynytimes}},
    url = {https://github.com/michadenheijer/pynytimes},
    version = {0.10.0},
    year = {2023},
    doi = {10.5281/zenodo.7821090}
}

If you're not using BibTeX, you can retrieve the preferred citation from Zenodo.

Disclaimer: This project is not made by anyone from the New York Times, nor is it affiliated with The New York Times Company.