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