Skip to main content

A Python wrapper for (most) New York Times APIs

Project description


Run full tests PyPI - Python Version PyPI Downloads DOI

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


Extensive documentation is available at:


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

Linux and Mac

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.

Supported APIs

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





Top stories

To get the current top stories use:

top_stories = nyt.top_stories()

Read the documentation to find the top stories per section.

Most viewed articles

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.

Most shared articles

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.

Article search

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.

Book reviews

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.

Movie reviews

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.

Best sellers lists

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.

Article metadata

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 = ""

Read additional parameters in the documentation.

Load latest articles

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.

Tag query

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

tags = nyt.tag_query(
    max_results = 20

Additional parameters can be found in the documentation.

Archive metadata

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.

Citing this Repository

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

    author = {Den Heijer, Micha},
    license = {MIT},
    title = {{pynytimes}},
    url = {},
    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.


License: MIT

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

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pynytimes-0.10.0.tar.gz (20.3 kB view hashes)

Uploaded Source

Built Distribution

pynytimes-0.10.0-py3-none-any.whl (20.5 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page