openapi: 3.0.0
servers:
  - url: https://api.nytimes.com/svc/books/v3
info:
  description: The Books API provides information about book reviews and The New York Times bestsellers lists.
  termsOfService: http://developer.nytimes.com/tou
  title: Books API
  version: 3.0.0
  x-apiClientRegistration:
    url: http://developer.nytimes.com/signup
  x-apisguru-categories:
    - media
    - open_data
  x-logo:
    url: https://static01.nyt.com/images/icons/t_logo_291_black.png
  x-origin:
    - format: openapi
      url: https://raw.githubusercontent.com/nytimes/public_api_specs/master/books_api/books_api.json
      version: "3.0"
  x-providerName: nytimes.com
  x-serviceName: books_api
externalDocs:
  url: http://developer.nytimes.com/
paths:
  /lists.{format}:
    get:
      description: ""
      operationId: GET_lists-format
      parameters:
        - description: |-
            The name of the Times best-seller list. To get valid values, use a list names request.

            Be sure to replace spaces with hyphens (e.g., e-book-fiction or hardcover-fiction, not E-Book Fiction or Hardcover Fiction). (The parameter is not case sensitive.)
          in: query
          name: list
          schema:
            type: string
        - description: The number of weeks that the best seller has been on list-name, as of bestsellers-date
          in: query
          name: weeks-on-list
          schema:
            type: integer
        - description: |-
            YYYY-MM-DD

            The week-ending date for the sales reflected on list-name. Times best-seller 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).
          in: query
          name: bestsellers-date
          schema:
            format: date-time
            type: string
        - description: YYYY-MM-DD  The date the best-seller list was published on NYTimes.com (compare bestsellers-date)
          in: query
          name: date
          schema:
            type: string
        - description: International Standard Book Number, 10 or 13 digits
          in: query
          name: isbn
          schema:
            type: string
        - description: |-
            YYYY-MM-DD

            The date the best-seller list was published on NYTimes.com (compare bestsellers-date)
          in: query
          name: published-date
          schema:
            type: string
        - description: The rank of the best seller on list-name as of bestsellers-date
          in: query
          name: rank
          schema:
            type: integer
        - description: The rank of the best seller on list-name one week prior to bestsellers-date
          in: query
          name: rank-last-week
          schema:
            type: integer
        - description: Sets the starting point of the result set
          in: query
          name: offset
          schema:
            multipleOf: 20
            type: integer
        - description: Sets the sort order of the result set
          in: query
          name: sort-order
          schema:
            enum:
              - ASC
              - DESC
            type: string
      responses:
        "200":
          content:
            application/json:
              examples:
                response:
                  value:
                    copyright: Copyright (c) 2016 The New York Times Company.  All Rights Reserved.
                    last_modified: 2016-03-11T13:09:01-05:00
                    num_results: 1
                    results:
                      - amazon_product_url: http://www.amazon.com/Girls-Guide-Moving-On-Novel-ebook/dp/B00ZNE17B4?tag=thenewyorktim-20
                        asterisk: 0
                        bestsellers_date: 2016-03-05
                        book_details:
                          - age_group: ""
                            author: Debbie Macomber
                            contributor: by Debbie Macomber
                            contributor_note: ""
                            description: A mother and her daughter-in-law both leave unhappy marriages and take up with new men.
                            price: 0
                            primary_isbn10: "0553391925"
                            primary_isbn13: "9780553391923"
                            publisher: Ballantine
                            title: A GIRL'S GUIDE TO MOVING ON
                        dagger: 0
                        display_name: Hardcover Fiction
                        isbns:
                          - isbn10: "0553391925"
                            isbn13: "9780553391923"
                        list_name: Hardcover Fiction
                        published_date: 2016-03-20
                        rank: 5
                        rank_last_week: 2
                        reviews:
                          - article_chapter_link: ""
                            book_review_link: ""
                            first_chapter_link: ""
                            sunday_review_link: ""
                        weeks_on_list: 2
                    status: OK
              schema:
                properties:
                  copyright:
                    type: string
                  last_modified:
                    type: string
                  num_results:
                    type: integer
                  results:
                    items:
                      properties:
                        amazon_product_url:
                          type: string
                        asterisk:
                          type: integer
                        bestsellers_date:
                          type: string
                        book_details:
                          items:
                            properties:
                              age_group:
                                type: string
                              author:
                                type: string
                              contributor:
                                type: string
                              contributor_note:
                                type: string
                              description:
                                type: string
                              price:
                                type: integer
                              primary_isbn10:
                                type: string
                              primary_isbn13:
                                type: string
                              publisher:
                                type: string
                              title:
                                type: string
                            type: object
                          type: array
                        dagger:
                          type: integer
                        display_name:
                          type: string
                        isbns:
                          items:
                            properties:
                              isbn10:
                                type: string
                              isbn13:
                                type: string
                            type: object
                          type: array
                        list_name:
                          type: string
                        published_date:
                          type: string
                        rank:
                          type: integer
                        rank_last_week:
                          type: integer
                        reviews:
                          items:
                            properties:
                              article_chapter_link:
                                type: string
                              book_review_link:
                                type: string
                              first_chapter_link:
                                type: string
                              sunday_review_link:
                                type: string
                            type: object
                          type: array
                        weeks_on_list:
                          type: integer
                      type: object
                    type: array
                  status:
                    type: string
                type: object
          description: ""
      security:
        - api-key: []
      summary: Best Seller List
    parameters:
      - in: path
        name: format
        required: true
        schema:
          enum:
            - json
            - jsonp
          type: string
        x-consoleDefault: json
  /lists/best-sellers/history.json:
    get:
      description: ""
      operationId: GET_lists-best-sellers-history-json
      parameters:
        - description: The target age group for the best seller.
          in: query
          name: age-group
          schema:
            type: string
        - 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. 
          in: query
          name: author
          schema:
            type: string
        - 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. 
          in: query
          name: contributor
          schema:
            type: string
        - 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).
          in: query
          name: isbn
          schema:
            type: string
        - description: The publisher's list price of the best seller, including decimal point
          in: query
          name: price
          schema:
            type: string
        - description: The standardized name of the publisher
          in: query
          name: publisher
          schema:
            type: string
        - description: |-
            The title of the best seller

            When searching, you can specify a portion of a title or a full title.
          in: query
          name: title
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              examples:
                response:
                  value:
                    copyright: Copyright (c) 2016 The New York Times Company.  All Rights Reserved.
                    num_results: 28970
                    results:
                      - age_group: ""
                        author: Sophia Amoruso
                        contributor: by Sophia Amoruso
                        contributor_note: ""
                        description: An online fashion retailer traces her path to success.
                        isbns:
                          - isbn10: 039916927X
                            isbn13: "9780399169274"
                        price: 0
                        publisher: Portfolio/Penguin/Putnam
                        ranks_history:
                          - asterisk: 0
                            bestsellers_date: 2016-02-27
                            dagger: 0
                            display_name: Business
                            list_name: Business Books
                            primary_isbn10: "1591847931"
                            primary_isbn13: "9781591847939"
                            published_date: 2016-03-13
                            rank: 8
                            ranks_last_week: null
                            weeks_on_list: 0
                        reviews:
                          - article_chapter_link: ""
                            book_review_link: ""
                            first_chapter_link: ""
                            sunday_review_link: ""
                        title: "#GIRLBOSS"
                    status: OK
              schema:
                properties:
                  copyright:
                    type: string
                  num_results:
                    type: integer
                  results:
                    items:
                      properties:
                        age_group:
                          type: string
                        author:
                          type: string
                        contributor:
                          type: string
                        contributor_note:
                          type: string
                        description:
                          type: string
                        isbns:
                          items:
                            properties:
                              isbn10:
                                type: string
                              isbn13:
                                type: string
                            type: object
                          type: array
                        price:
                          type: integer
                        publisher:
                          type: string
                        ranks_history:
                          items:
                            properties:
                              asterisk:
                                type: integer
                              bestsellers_date:
                                type: string
                              dagger:
                                type: integer
                              display_name:
                                type: string
                              list_name:
                                type: string
                              primary_isbn10:
                                type: string
                              primary_isbn13:
                                type: string
                              published_date:
                                type: string
                              rank:
                                type: integer
                              ranks_last_week:
                                nullable: true
                              weeks_on_list:
                                type: integer
                            type: object
                          type: array
                        reviews:
                          items:
                            properties:
                              article_chapter_link:
                                type: string
                              book_review_link:
                                type: string
                              first_chapter_link:
                                type: string
                              sunday_review_link:
                                type: string
                            type: object
                          type: array
                        title:
                          type: string
                      type: object
                    type: array
                  status:
                    type: string
                type: object
          description: ""
      security:
        - api-key: []
      summary: Best Seller History List
    parameters: []
  /lists/names.{format}:
    get:
      description: ""
      operationId: GET_lists-names-format
      parameters:
        - in: query
          name: api-key
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              examples:
                response:
                  value:
                    copyright: Copyright (c) 2016 The New York Times Company.  All Rights Reserved.
                    num_results: 53
                    results:
                      - display_name: Combined Print & E-Book Fiction
                        list_name: Combined Print and E-Book Fiction
                        list_name_encoded: combined-print-and-e-book-fiction
                        newest_published_date: 2016-03-20
                        oldest_published_date: 2011-02-13
                        updated: WEEKLY
                    status: OK
              schema:
                properties:
                  copyright:
                    type: string
                  num_results:
                    type: integer
                  results:
                    items:
                      properties:
                        display_name:
                          type: string
                        list_name:
                          type: string
                        list_name_encoded:
                          type: string
                        newest_published_date:
                          type: string
                        oldest_published_date:
                          type: string
                        updated:
                          type: string
                      type: object
                    type: array
                  status:
                    type: string
                type: object
          description: ""
      security:
        - api-key: []
      summary: Best Seller List Names
    parameters:
      - in: path
        name: format
        required: true
        schema:
          enum:
            - json
            - jsonp
          type: string
  /lists/overview.{format}:
    get:
      description: ""
      operationId: GET_lists-overview-format
      parameters:
        - description: |-
            The best-seller list publication date. YYYY-MM-DD

            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.
          in: query
          name: published_date
          schema:
            type: string
        - in: query
          name: api-key
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              examples:
                response:
                  value:
                    copyright: Copyright (c) 2016 The New York Times Company.  All Rights Reserved.
                    num_results: 210
                    results:
                      bestsellers_date: 2016-03-05
                      lists:
                        - 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_isbn10: "0698406427"
                              primary_isbn13: "9780698406421"
                              publisher: Putnam
                              rank: 1
                              title: THE GANGSTER
                              updated_date: 2016-03-10 17:00:21
                          display_name: Combined Print & E-Book Fiction
                          list_id: 704
                          list_image: http://du.ec2.nytimes.com.s3.amazonaws.com/prd/books/9780399175954.jpg
                          list_name: Combined Print and E-Book Fiction
                          updated: WEEKLY
                      published_date: 2016-03-20
                    status: OK
              schema:
                properties:
                  copyright:
                    type: string
                  num_results:
                    type: integer
                  results:
                    properties:
                      bestsellers_date:
                        type: string
                      lists:
                        items:
                          properties:
                            books:
                              items:
                                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_isbn10:
                                    type: string
                                  primary_isbn13:
                                    type: string
                                  publisher:
                                    type: string
                                  rank:
                                    type: integer
                                  title:
                                    type: string
                                  updated_date:
                                    type: string
                                type: object
                              type: array
                            display_name:
                              type: string
                            list_id:
                              type: integer
                            list_image:
                              type: string
                            list_name:
                              type: string
                            updated:
                              type: string
                          type: object
                        type: array
                      published_date:
                        type: string
                    type: object
                  status:
                    type: string
                type: object
          description: ""
      security:
        - api-key: []
      summary: Best Seller List Overview
    parameters:
      - in: path
        name: format
        required: true
        schema:
          enum:
            - json
            - jsonp
          type: string
  /lists/{date}/{list}.json:
    get:
      description: ""
      operationId: GET_lists-date-list-json
      parameters:
        - description: International Standard Book Number, 10 or 13 digits
          in: query
          name: isbn
          schema:
            type: integer
        - description: |-
            The name of the Times best-seller list. To get valid values, use a list names request.

            Be sure to replace spaces with hyphens (e.g., e-book-fiction or hardcover-fiction, not E-Book Fiction or Hardcover Fiction). (The parameter is not case sensitive.)
          in: query
          name: list-name
          schema:
            type: string
        - description: |-
            YYYY-MM-DD

            The date the best-seller list was published on NYTimes.com (compare bestsellers-date)
          in: query
          name: published-date
          schema:
            format: date-time
            type: string
        - description: |-
            YYYY-MM-DD

            The week-ending date for the sales reflected on list-name. Times best-seller 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).
          in: query
          name: bestsellers-date
          schema:
            type: string
        - description: The number of weeks that the best seller has been on list-name, as of bestsellers-date
          in: query
          name: weeks-on-list
          schema:
            type: integer
        - description: The rank of the best seller on list-name as of bestsellers-date
          in: query
          name: rank
          schema:
            type: string
        - description: The rank of the best seller on list-name one week prior to bestsellers-date
          in: query
          name: rank-last-week
          schema:
            type: integer
        - description: Sets the starting point of the result set
          in: query
          name: offset
          schema:
            multipleOf: 20
            type: integer
        - description: The default is ASC (ascending). The sort-order parameter is used with the sort-by parameter — for details, see each request type.
          in: query
          name: sort-order
          schema:
            enum:
              - ASC
              - DESC
            type: string
      responses:
        "200":
          content:
            application/json:
              examples:
                response:
                  value:
                    copyright: Copyright (c) 2016 The New York Times Company.  All Rights Reserved.
                    last_modified: 2015-12-25T13:05:20-05:00
                    num_results: 15
                    results:
                      bestsellers_date: 2015-12-19
                      books:
                        - age_group: ""
                          amazon_product_url: http://www.amazon.com/The-Martian-Novel-Andy-Weir-ebook/dp/B00EMXBDMA?tag=thenewyorktim-20
                          article_chapter_link: ""
                          asterisk: 0
                          author: Andy Weir
                          book_image: http://du.ec2.nytimes.com.s3.amazonaws.com/prd/books/9780804139038.jpg
                          book_review_link: ""
                          contributor: by Andy Weir
                          contributor_note: ""
                          dagger: 0
                          description: Separated from his crew, an astronaut embarks on a quest to stay alive on Mars. The basis of the movie.
                          first_chapter_link: ""
                          isbns:
                            - isbn10: "0804139024"
                              isbn13: "9780804139021"
                          price: 0
                          primary_isbn10: "0553418025"
                          primary_isbn13: "9780553418026"
                          publisher: Broadway
                          rank: 1
                          rank_last_week: 0
                          sunday_review_link: ""
                          title: THE MARTIAN
                          weeks_on_list: 60
                      corrections: []
                      display_name: Paperback Trade Fiction
                      list_name: Trade Fiction Paperback
                      normal_list_ends_at: 10
                      published_date: 2016-01-03
                      updated: WEEKLY
                    status: OK
              schema:
                properties:
                  copyright:
                    type: string
                  last_modified:
                    type: string
                  num_results:
                    type: integer
                  results:
                    properties:
                      bestsellers_date:
                        type: string
                      books:
                        items:
                          properties:
                            age_group:
                              type: string
                            amazon_product_url:
                              type: string
                            article_chapter_link:
                              type: string
                            asterisk:
                              type: integer
                            author:
                              type: string
                            book_image:
                              type: string
                            book_review_link:
                              type: string
                            contributor:
                              type: string
                            contributor_note:
                              type: string
                            dagger:
                              type: integer
                            description:
                              type: string
                            first_chapter_link:
                              type: string
                            isbns:
                              items:
                                properties:
                                  isbn10:
                                    type: string
                                  isbn13:
                                    type: string
                                type: object
                              type: array
                            price:
                              type: integer
                            primary_isbn10:
                              type: string
                            primary_isbn13:
                              type: string
                            publisher:
                              type: string
                            rank:
                              type: integer
                            rank_last_week:
                              type: integer
                            sunday_review_link:
                              type: string
                            title:
                              type: string
                            weeks_on_list:
                              type: integer
                          type: object
                        type: array
                      corrections:
                        items:
                          properties: {}
                          type: object
                        type: array
                      display_name:
                        type: string
                      list_name:
                        type: string
                      normal_list_ends_at:
                        type: integer
                      published_date:
                        type: string
                      updated:
                        type: string
                    type: object
                  status:
                    type: string
                type: object
          description: ""
      security:
        - api-key: []
      summary: Best Seller List by Date
    parameters:
      - in: path
        name: date
        required: true
        schema:
          type: string
      - description: Name of the Best Sellers List. You can get the full list from /lists/names.json
        in: path
        name: list
        required: true
        schema:
          type: string
  /reviews.{format}:
    get:
      description: ""
      operationId: GET_reviews-format
      parameters:
        - description: Searching by ISBN is the recommended method. You can enter 10- or 13-digit ISBNs.
          in: query
          name: isbn
          schema:
            type: integer
        - description: You’ll need to enter the full title of the book. Spaces in the title will be converted into the characters %20.
          in: query
          name: title
          schema:
            type: string
        - 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.
          in: query
          name: author
          schema:
            type: string
        - in: query
          name: api-key
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              examples:
                response:
                  value:
                    copyright: Copyright (c) 2016 The New York Times Company.  All Rights Reserved.
                    num_results: 2
                    results:
                      - book_author: Haruki Murakami
                        book_title: 1Q84
                        byline: JANET MASLIN
                        isbn13:
                          - "9780307476463"
                        publication_dt: 2011-11-10
                        summary: In “1Q84,” the Japanese novelist Haruki Murakami writes about characters in a Tokyo with two moons.
                        url: http://www.nytimes.com/2011/11/10/books/1q84-by-haruki-murakami-review.html
                    status: OK
              schema:
                properties:
                  copyright:
                    type: string
                  num_results:
                    type: integer
                  results:
                    items:
                      properties:
                        book_author:
                          type: string
                        book_title:
                          type: string
                        byline:
                          type: string
                        isbn13:
                          items:
                            type: string
                          type: array
                        publication_dt:
                          type: string
                        summary:
                          type: string
                        url:
                          type: string
                      type: object
                    type: array
                  status:
                    type: string
                type: object
          description: ""
      security:
        - api-key: []
      summary: Reviews
    parameters:
      - in: path
        name: format
        required: true
        schema:
          enum:
            - json
            - jsonp
          type: string
components:
  securitySchemes:
    api-key:
      in: query
      name: api-key
      type: apiKey
