pynytimes

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

Documentation

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

Installation

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

Windows

python -m pip install --upgrade pynytimes

Usage

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.

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)

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 = "https://www.nytimes.com/2019/10/20/world/middleeast/erdogan-turkey-nuclear-weapons-trump.html"
)

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(
    "pentagon",
    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:

@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.

License

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