Books API
Provides information about NYT book reviews and The New York Times Best Sellers lists. Some lists are weekly and some monthly. Supports current and historical date lookups, list metadata, and review lookup by author, ISBN, or title.
OpenAPI Specification
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