The New York Times Books API
The Books API provides information about book reviews and The New York Times Best Sellers lists. Access current and historical bestseller lists, book details, and NYT critic reviews.
OpenAPI Specification
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
nam
# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/the-new-york-times/refs/heads/main/openapi/new-york-times-books-openapi-original.yml