Books API

swagger: '2.0'
basePath: /svc/books/v3
host: api.nytimes.com
schemes:
  - https
info:
  version: 3.0.0
  title: Books API
  description: |
    The Books API provides information about book reviews and The New York Times Best Sellers lists.

    ## Best Sellers Lists Services
    ### List Names
    The lists/names service returns a list of all the NYT Best Sellers Lists.  Some lists are published weekly and others monthly.  The response includes when each list was first published and last published.

    ```
    /lists/names.json
    ```

    ### List Data

    The lists/{date}/{name} service returns the books on the best sellers list for the specified date and list name.

    ```
    /lists/2019-01-20/hardcover-fiction.json
    ```

    Use "current" for {date} to get the latest list.
    ```
    /lists/current/hardcover-fiction.json
    ```

    ## Book Reviews Services

    The book reviews service lets you get NYT book review by author, ISBN, or title.

    ```
    /reviews.json?author=Michelle+Obama
    ```

    ```
    /reviews.json?isbn=9781524763138
    ```

    ```
    /reviews.json?title=Becoming
    ```

    ## Example Calls

    ```
    https://api.nytimes.com/svc/books/v3/lists/current/hardcover-fiction.json?api-key=yourkey
    ```

    ```
    https://api.nytimes.com/svc/books/v3/reviews.json?author=Stephen+King&api-key=yourkey
    ```
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
      consumes:
        - application/json
      produces:
        - application/json
      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).
          type: string
          required: true
          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).
          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.
          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.
          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: 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
          examples:
            application/json:
              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: []
  '/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: []
  '/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: []
  '/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: []
  '/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: []
  '/reviews.json':
    get:
      summary: Reviews
      description: 'Get book reviews.'
      operationId: GET_reviews-format
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: isbn
          in: query
          description: Searching by ISBN is the recommended method. You can enter 10- or 13-digit ISBNs.
          type: integer
        - name: title
          in: query
          description: You’ll need to enter the full title of the book. Spaces in the title will be converted into the characters %20.
          type: string
        - name: author
          in: query
          description: 'You’ll need to enter the author’s first and last name, separated by a space. This space will be converted into the characters %20.'
          type: string
      responses:
        '200':
          description: 'Book reviews.'
          schema:
            type: object
            properties:
              status:
                type: string
              copyright:
                type: string
              num_results:
                type: integer
              results:
                type: array
                items:
                  type: object
                  properties:
                    url:
                      type: string
                    publication_dt:
                      type: string
                    byline:
                      type: string
                    book_title:
                      type: string
                    book_author:
                      type: string
                    summary:
                      type: string
                    isbn13:
                      type: array
                      items:
                        type: string
          examples:
            application/json:
              status: OK
              copyright: Copyright (c) 2019 The New York Times Company.  All Rights Reserved.
              num_results: 2
              results:
                - url: 'http://www.nytimes.com/2011/11/10/books/1q84-by-haruki-murakami-review.html'
                  publication_dt: '2011-11-10'
                  byline: JANET MASLIN
                  book_title: 1Q84
                  book_author: Haruki Murakami
                  summary: 'In “1Q84,” the Japanese novelist Haruki Murakami writes about characters in a Tokyo with two moons.'
                  isbn13:
                    - '9780307476463'
      security:
        - api-key: []
definitions: {}
securityDefinitions:
  api-key:
    name: api-key
    type: apiKey
    in: query