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://api.apis.guru/v2/cache/logo/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