The New York Times Company

The New York Times Company Lists.json API

The Lists.json API from The New York Times Company — 1 operation(s) for lists.json.

Documentation GitHub OpenAPI

Operations 1

GET /lists.json Best Sellers List #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/new-york-times-company-lists-json-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  version: 2.0.0
  title: Archive Lists.json API
  description: 'The Archive API returns an array of NYT articles for a given month, going back to 1851.  Its response fields are the same as the Article Search API. The Archive API is very useful if you want to build your own database of NYT article metadata. You simply pass the API the year and month and it returns a JSON object with all articles for that month.  The response size can be large (~20mb).


    ```

    /{year}/{month}.json

    ```


    ## Example Call

    ```

    https://api.nytimes.com/svc/archive/v1/2019/1.json?api-key=yourkey

    ```

    '
servers:
- url: https://api.nytimes.com/svc/archive/v1
security:
- apikey: []
tags:
- name: Lists.json
paths:
  /lists.json:
    get:
      summary: Best Sellers List
      description: Get Best Sellers list.  If no date is provided returns the latest list.
      operationId: GET_lists-format
      parameters:
      - name: list
        in: query
        description: 'The name of the Times best sellers list (hardcover-fiction, paperback-nonfiction, ...).

          The /lists/names service returns all the list names.

          The encoded list names are lower case with hyphens instead of spaces (e.g. e-book-fiction, instead of E-Book Fiction).'
        required: true
        schema:
          type: string
          default: hardcover-fiction
      - name: bestsellers-date
        in: query
        description: 'YYYY-MM-DD


          The week-ending date for the sales reflected on list-name. Times best sellers lists are compiled using available book sale data. The bestsellers-date may be significantly earlier than published-date. For additional information, see the explanation at the bottom of any best-seller list page on NYTimes.com (example: Hardcover Fiction, published Dec. 5 but reflecting sales to Nov. 29).'
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      - name: published-date
        in: query
        description: 'YYYY-MM-DD


          The date the best sellers list was published on NYTimes.com (different than bestsellers-date).  Use "current" for latest list.'
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      - name: offset
        in: query
        description: Sets the starting point of the result set (0, 20, ...).  Used to paginate thru books if list has more than 20. Defaults to 0.  The num_results field indicates how many books are in the list.
        schema:
          type: integer
          multipleOf: 20
      responses:
        '200':
          description: Best Sellers list books
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  copyright:
                    type: string
                  num_results:
                    type: integer
                  last_modified:
                    type: string
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        list_name:
                          type: string
                        display_name:
                          type: string
                        bestsellers_date:
                          type: string
                        published_date:
                          type: string
                        rank:
                          type: integer
                        rank_last_week:
                          type: integer
                        weeks_on_list:
                          type: integer
                        asterisk:
                          type: integer
                        dagger:
                          type: integer
                        amazon_product_url:
                          type: string
                        isbns:
                          type: array
                          items:
                            type: object
                            properties:
                              isbn10:
                                type: string
                              isbn13:
                                type: string
                        book_details:
                          type: array
                          items:
                            type: object
                            properties:
                              title:
                                type: string
                              description:
                                type: string
                              contributor:
                                type: string
                              author:
                                type: string
                              contributor_note:
                                type: string
                              price:
                                type: integer
                              age_group:
                                type: string
                              publisher:
                                type: string
                              primary_isbn13:
                                type: string
                              primary_isbn10:
                                type: string
                        reviews:
                          type: array
                          items:
                            type: object
                            properties:
                              book_review_link:
                                type: string
                              first_chapter_link:
                                type: string
                              sunday_review_link:
                                type: string
                              article_chapter_link:
                                type: string
              example:
                status: OK
                copyright: Copyright (c) 2019 The New York Times Company.  All Rights Reserved.
                num_results: 1
                last_modified: '2016-03-11T13:09:01-05:00'
                results:
                - list_name: Hardcover Fiction
                  display_name: Hardcover Fiction
                  bestsellers_date: '2016-03-05'
                  published_date: '2016-03-20'
                  rank: 5
                  rank_last_week: 2
                  weeks_on_list: 2
                  asterisk: 0
                  dagger: 0
                  amazon_product_url: http://www.amazon.com/Girls-Guide-Moving-On-Novel-ebook/dp/B00ZNE17B4?tag=thenewyorktim-20
                  isbns:
                  - isbn10: 0553391925
                    isbn13: '9780553391923'
                  book_details:
                  - title: A GIRL'S GUIDE TO MOVING ON
                    description: A mother and her daughter-in-law both leave unhappy marriages and take up with new men.
                    contributor: by Debbie Macomber
                    author: Debbie Macomber
                    contributor_note: ''
                    price: 0
                    age_group: ''
                    publisher: Ballantine
                    primary_isbn13: '9780553391923'
                    primary_isbn10: 0553391925
                  reviews:
                  - book_review_link: ''
                    first_chapter_link: ''
                    sunday_review_link: ''
                    article_chapter_link: ''
      security:
      - api-key: []
      tags:
      - Lists.json
components:
  securitySchemes:
    apikey:
      type: apiKey
      name: api-key
      in: query

The New York Times Company Lists.json API

Operations 1

Documentation

Specifications

Schemas & Data

Other Resources