The New York Times Company Lists API

openapi: 3.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

    ```

    '
servers:
- url: https://api.nytimes.com/svc/archive/v1
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
      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
        schema:
          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
        schema:
          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.
        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: 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: {}
              example:
                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
      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.'
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      responses:
        '200':
          description: Overview of Best Sellers lists.
          content:
            application/json:
              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
              example:
                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
      responses:
        '200':
          description: Get Best Sellers list names.
          content:
            application/json:
              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
              example:
                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
      parameters:
      - name: age-group
        in: query
        description: The target age group for the best seller.
        schema:
          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.'
        schema:
          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.'
        schema:
          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).'
        schema:
          type: string
      - name: price
        in: query
        description: The publisher's list price of the best seller, including decimal point.
        schema:
          type: string
      - name: publisher
        in: query
        description: The standardized name of the publisher
        schema:
          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.'
        schema:
          type: string
      responses:
        '200':
          description: Best Sellers list history
          content:
            application/json:
              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
              example:
                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
components:
  securitySchemes:
    apikey:
      type: apiKey
      name: api-key
      in: query