The New York Times Company
The New York Times Company Lists API

The Lists API from The New York Times Company — 4 operation(s) for lists.
Documentation GitHub OpenAPI
OpenAPI Specification

swagger: '2.0'
info:
  version: 2.0.0
  title: Archive Lists 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

    ```

    '
host: api.nytimes.com
basePath: /svc/archive/v1
schemes:
- https
produces:
- application/json
security:
- apikey: []
tags:
- name: Lists
paths:
  /lists/{date}/{list}.json:
    get:
      summary: Best Sellers List by Date
      description: Get Best Sellers list by date.
      operationId: GET_lists-date-list-json
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: date
        in: path
        description: 'YYYY-MM-DD or "current"


          The date the best sellers list was published on NYTimes.com.  Use "current" to get latest list.'
        required: true
        type: string
        pattern: ^(\d{4}-\d{2}-\d{2}|current)$
      - name: list
        in: path
        description: Name of the Best Sellers List (e.g. hardcover-fiction). You can get the full list of names from the /lists/names.json service.
        required: true
        type: string
      - 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.
        type: integer
        multipleOf: 20
      responses:
        '200':
          description: Best Sellers list books.
          schema:
            type: object
            properties:
              status:
                type: string
              copyright:
                type: string
              num_results:
                type: integer
              last_modified:
                type: string
              results:
                type: object
                properties:
                  list_name:
                    type: string
                  bestsellers_date:
                    type: string
                  published_date:
                    type: string
                  display_name:
                    type: string
                  normal_list_ends_at:
                    type: integer
                  updated:
                    type: string
                  books:
                    type: array
                    items:
                      type: object
                      properties:
                        rank:
                          type: integer
                        rank_last_week:
                          type: integer
                        weeks_on_list:
                          type: integer
                        asterisk:
                          type: integer
                        dagger:
                          type: integer
                        primary_isbn10:
                          type: string
                        primary_isbn13:
                          type: string
                        publisher:
                          type: string
                        description:
                          type: string
                        price:
                          type: integer
                        title:
                          type: string
                        author:
                          type: string
                        contributor:
                          type: string
                        contributor_note:
                          type: string
                        book_image:
                          type: string
                        amazon_product_url:
                          type: string
                        age_group:
                          type: string
                        book_review_link:
                          type: string
                        first_chapter_link:
                          type: string
                        sunday_review_link:
                          type: string
                        article_chapter_link:
                          type: string
                        isbns:
                          type: array
                          items:
                            type: object
                            properties:
                              isbn10:
                                type: string
                              isbn13:
                                type: string
                  corrections:
                    type: array
                    items:
                      type: object
                      properties: {}
          examples:
            application/json:
              status: OK
              copyright: Copyright (c) 2019 The New York Times Company.  All Rights Reserved.
              num_results: 15
              last_modified: '2015-12-25T13:05:20-05:00'
              results:
                list_name: Trade Fiction Paperback
                bestsellers_date: '2015-12-19'
                published_date: '2016-01-03'
                display_name: Paperback Trade Fiction
                normal_list_ends_at: 10
                updated: WEEKLY
                books:
                - rank: 1
                  rank_last_week: 0
                  weeks_on_list: 60
                  asterisk: 0
                  dagger: 0
                  primary_isbn10: 0553418025
                  primary_isbn13: '9780553418026'
                  publisher: Broadway
                  description: Separated from his crew, an astronaut embarks on a quest to stay alive on Mars. The basis of the movie.
                  price: 0
                  title: THE MARTIAN
                  author: Andy Weir
                  contributor: by Andy Weir
                  contributor_note: ''
                  book_image: http://du.ec2.nytimes.com.s3.amazonaws.com/prd/books/9780804139038.jpg
                  amazon_product_url: http://www.amazon.com/The-Martian-Novel-Andy-Weir-ebook/dp/B00EMXBDMA?tag=thenewyorktim-20
                  age_group: ''
                  book_review_link: ''
                  first_chapter_link: ''
                  sunday_review_link: ''
                  article_chapter_link: ''
                  isbns:
                  - isbn10: 0804139024
                    isbn13: '9780804139021'
                corrections: []
      security:
      - api-key: []
      tags:
      - Lists
  /lists/overview.json:
    get:
      summary: Best Sellers List Overview
      description: Get top 5 books for all the Best Sellers lists for specified date.
      operationId: GET_lists-overview-format
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: published_date
        in: query
        description: 'YYYY-MM-DD


          The best-seller list publication date.

          You do not have to specify the exact date the list was published. The service will search forward (into the future) for the closest publication date to the date you specify. For example, a request for lists/overview/2013-05-22 will retrieve the list that was published on 05-26.


          If you do not include a published date, the current week''s best sellers lists will be returned.'
        type: string
        pattern: ^\d{4}-\d{2}-\d{2}$
      responses:
        '200':
          description: Overview of Best Sellers lists.
          schema:
            type: object
            properties:
              status:
                type: string
              copyright:
                type: string
              num_results:
                type: integer
              results:
                type: object
                properties:
                  bestsellers_date:
                    type: string
                  published_date:
                    type: string
                  lists:
                    type: array
                    items:
                      type: object
                      properties:
                        list_id:
                          type: integer
                        list_name:
                          type: string
                        display_name:
                          type: string
                        updated:
                          type: string
                        list_image:
                          type: string
                        books:
                          type: array
                          items:
                            type: object
                            properties:
                              age_group:
                                type: string
                              author:
                                type: string
                              contributor:
                                type: string
                              contributor_note:
                                type: string
                              created_date:
                                type: string
                              description:
                                type: string
                              price:
                                type: integer
                              primary_isbn13:
                                type: string
                              primary_isbn10:
                                type: string
                              publisher:
                                type: string
                              rank:
                                type: integer
                              title:
                                type: string
                              updated_date:
                                type: string
          examples:
            application/json:
              status: OK
              copyright: Copyright (c) 2019 The New York Times Company.  All Rights Reserved.
              num_results: 210
              results:
                bestsellers_date: '2016-03-05'
                published_date: '2016-03-20'
                lists:
                - list_id: 704
                  list_name: Combined Print and E-Book Fiction
                  display_name: Combined Print & E-Book Fiction
                  updated: WEEKLY
                  list_image: http://du.ec2.nytimes.com.s3.amazonaws.com/prd/books/9780399175954.jpg
                  books:
                  - age_group: ''
                    author: Clive Cussler and Justin Scott
                    contributor: by Clive Cussler and Justin Scott
                    contributor_note: ''
                    created_date: '2016-03-10 12:00:22'
                    description: In the ninth book in this series, set in 1906, the New York detective Isaac Bell contends with a crime boss passing as a respectable businessman and a tycoon’s plot against President Theodore Roosevelt.
                    price: 0
                    primary_isbn13: '9780698406421'
                    primary_isbn10: 0698406427
                    publisher: Putnam
                    rank: 1
                    title: THE GANGSTER
                    updated_date: '2016-03-10 17:00:21'
      security:
      - api-key: []
      tags:
      - Lists
  /lists/names.json:
    get:
      summary: Best Sellers List Names
      description: Get Best Sellers list names.
      operationId: GET_lists-names-format
      consumes:
      - application/json
      produces:
      - application/json
      responses:
        '200':
          description: Get Best Sellers list names.
          schema:
            type: object
            properties:
              status:
                type: string
              copyright:
                type: string
              num_results:
                type: integer
              results:
                type: array
                items:
                  type: object
                  properties:
                    list_name:
                      type: string
                    display_name:
                      type: string
                    list_name_encoded:
                      type: string
                    oldest_published_date:
                      type: string
                    newest_published_date:
                      type: string
                    updated:
                      type: string
                      enum:
                      - WEEKLY
                      - MONTHLY
          examples:
            application/json:
              status: OK
              copyright: Copyright (c) 2019 The New York Times Company.  All Rights Reserved.
              num_results: 53
              results:
              - list_name: Combined Print and E-Book Fiction
                display_name: Combined Print & E-Book Fiction
                list_name_encoded: combined-print-and-e-book-fiction
                oldest_published_date: '2011-02-13'
                newest_published_date: '2016-03-20'
                updated: WEEKLY
      security:
      - api-key: []
      tags:
      - Lists
  /lists/best-sellers/history.json:
    get:
      summary: Best Sellers List History
      description: Get Best Sellers list history.
      operationId: GET_lists-best-sellers-history-json
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: age-group
        in: query
        description: The target age group for the best seller.
        type: string
      - name: author
        in: query
        description: 'The author of the best seller. The author field does not include additional contributors (see Data Structure for more details about the author and contributor fields).


          When searching the author field, you can specify any combination of first, middle and last names.


          When sort-by is set to author, the results will be sorted by author''s first name.'
        type: string
      - name: contributor
        in: query
        description: 'The author of the best seller, as well as other contributors such as the illustrator (to search or sort by author name only, use author instead).


          When searching, you can specify any combination of first, middle and last names of any of the contributors.


          When sort-by is set to contributor, the results will be sorted by the first name of the first contributor listed.'
        type: string
      - name: isbn
        in: query
        description: 'International Standard Book Number, 10 or 13 digits


          A best seller may have both 10-digit and 13-digit ISBNs, and may have multiple ISBNs of each type. To search on multiple ISBNs, separate the ISBNs with semicolons (example: 9780446579933;0061374229).'
        type: string
      - name: price
        in: query
        description: The publisher's list price of the best seller, including decimal point.
        type: string
      - name: publisher
        in: query
        description: The standardized name of the publisher
        type: string
      - name: title
        in: query
        description: 'The title of the best seller


          When searching, you can specify a portion of a title or a full title.'
        type: string
      responses:
        '200':
          description: Best Sellers list history
          schema:
            type: object
            properties:
              status:
                type: string
              copyright:
                type: string
              num_results:
                type: integer
              results:
                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
                    isbns:
                      type: array
                      items:
                        type: object
                        properties:
                          isbn10:
                            type: string
                          isbn13:
                            type: string
                    ranks_history:
                      type: array
                      items:
                        type: object
                        properties:
                          primary_isbn10:
                            type: string
                          primary_isbn13:
                            type: string
                          rank:
                            type: integer
                          list_name:
                            type: string
                          display_name:
                            type: string
                          published_date:
                            type: string
                          bestsellers_date:
                            type: string
                          weeks_on_list:
                            type: integer
                          ranks_last_week:
                            type: 'null'
                          asterisk:
                            type: integer
                          dagger:
                            type: integer
                    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
          examples:
            application/json:
              status: OK
              copyright: Copyright (c) 2019 The New York Times Company.  All Rights Reserved.
              num_results: 28970
              results:
              - title: '#GIRLBOSS'
                description: An online fashion retailer traces her path to success.
                contributor: by Sophia Amoruso
                author: Sophia Amoruso
                contributor_note: ''
                price: 0
                age_group: ''
                publisher: Portfolio/Penguin/Putnam
                isbns:
                - isbn10: 039916927X
                  isbn13: '9780399169274'
                ranks_history:
                - primary_isbn10: '1591847931'
                  primary_isbn13: '9781591847939'
                  rank: 8
                  list_name: Business Books
                  display_name: Business
                  published_date: '2016-03-13'
                  bestsellers_date: '2016-02-27'
                  weeks_on_list: 0
                  ranks_last_week: null
                  asterisk: 0
                  dagger: 0
                reviews:
                - book_review_link: ''
                  first_chapter_link: ''
                  sunday_review_link: ''
                  article_chapter_link: ''
      security:
      - api-key: []
      tags:
      - Lists
securityDefinitions:
  apikey:
    type: apiKey
    name: api-key
    in: query
The New York Times Company Lists API

Documentation

Specifications

Schemas & Data

Other Resources

OpenAPI Specification
