Skip to main content

Python wrapper for NYTimes Top Stories API

Project description

nytimes-top-stories is a simple Python wrapper for New York Times’ Top Stories API.

Compatible with Python 2.7 and 3+.


nytimes-top-stories requires the requests package.



pip install nytimes-top-stories

Clone repository

  • git clone

  • cd into your nytimes-top-stories directory

  • python install


Register for a Top Stories API key at

from topstories import TopStoriesAPI
api = TopStoriesAPI(<SECRET_API_KEY>)

The get_stories method takes one required argument and two optional arguments. Checkout the API documentation to see the data that is returned from the API.

def get_stories(self, section, format_type="json", return_json_string=False):
  Gets a list of current top articles and associated images in the
  specified section and in the specified format.

      section: (string) the section the articles appears in
      format: (string) json or jsonp, default is json
      return_json_string: (boolean) if True, return value will be JSON string instead of a python list,
                          default is False
      format_type=json: A list of articles (articles are python dicts) is returned.
                        If return_json_string, string is returned.
      format_type=jsonp: API returns a callback function (string) in the format
                        {data} is an object, not an array, and it is not parsed/decoded.
stories = api.get_stories("politics") # list of story dicts
stories_string = api.get_stories("home", return_json_string=True) # json string
stories_jsonp = api.get_stories("work", format_type="jsonp") # (string) callback function with data input

In addition, there are two more public methods:

#returns a list of valid sections
>>> api.get_sections_list()
>>> ["home","opinion","world","national","politics","upshot","nyregion","business",
# writes a list of stories to a json file
# input a path to file and list of stories
api.write_to_json_file("example.json", stories)


pytest and mock are used for testing this package.

python pytest

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

nytimes-top-stories-1.0.1.tar.gz (3.8 kB view hashes)

Uploaded source

Built Distribution

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