Query structured spec data via REST or MCP. Get exactly what your agent needs.
https://api.nytimes.com/svc/books/v3
/lists.json
Get Best Sellers list. If no date is provided returns the latest list.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| list | query | required | string | 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). |
| bestsellers-date | query | optional | string | 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). |
| published-date | query | optional | string | YYYY-MM-DD The date the best sellers list was published on NYTimes.com (different than bestsellers-date). Use "current" for latest list. |
| offset | query | optional | integer | 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. |
GET /lists.json
/lists/best-sellers/history.json
Get Best Sellers list history.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| age-group | query | optional | string | The target age group for the best seller. |
| author | query | optional | string | 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. |
| contributor | query | optional | string | 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. |
| isbn | query | optional | string | 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). |
| offset | query | optional | integer | Sets the starting point of the result set (0, 20, ...). Used to paginate thru results if there are more than 20. Defaults to 0. The num_results field indicates how many results there are total. |
| price | query | optional | string | The publisher's list price of the best seller, including decimal point. |
| publisher | query | optional | string | The standardized name of the publisher |
| title | query | optional | string | The title of the best seller When searching, you can specify a portion of a title or a full title. |
GET /lists/best-sellers/history.json
/lists/full-overview.json
Get all books for all the Best Sellers lists for specified date.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| published_date | query | optional | string | 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. |
GET /lists/full-overview.json
/lists/names.json
Get Best Sellers list names.
GET /lists/names.json
/lists/overview.json
Get top 5 books for all the Best Sellers lists for specified date.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| published_date | query | optional | string | 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. |
GET /lists/overview.json
/lists/{date}/{list}.json
Get Best Sellers list by date.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| date | path | required | string | YYYY-MM-DD or "current" The date the best sellers list was published on NYTimes.com. Use "current" to get latest list. |
| list | path | required | string | Name of the Best Sellers List (e.g. hardcover-fiction). You can get the full list of names from the /lists/names.json service. |
| offset | query | optional | integer | 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. |
GET /lists/{date}/{list}.json
/reviews.json
Get book reviews.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| isbn | query | optional | integer | Searching by ISBN is the recommended method. You can enter 10- or 13-digit ISBNs. |
| title | query | optional | string | You’ll need to enter the full title of the book. Spaces in the title will be converted into the characters %20. |
| author | query | optional | string | 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. |
GET /reviews.json
ListGetBestSellersResponse
{
"type": "object",
"properties": {
"status": {
"type": "string"
},
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"rank": {
"type": "integer"
},
"isbns": {
"type": "array",
"items": {
"type": "object",
"properties": {
"isbn10": {
"type": "string"
},
"isbn13": {
"type": "string"
}
}
}
},
"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"
}
}
}
},
"asterisk": {
"type": "integer"
},
"list_name": {
"type": "string"
},
"book_details": {
"type": "array",
"items": {
"type": "object",
"properties": {
"price": {
"type": "integer"
},
"title": {
"type": "string"
},
"author": {
"type": "string"
},
"age_group": {
"type": "string"
},
"publisher": {
"type": "string"
},
"contributor": {
"type": "string"
},
"description": {
"type": "string"
},
"primary_isbn10": {
"type": "string"
},
"primary_isbn13": {
"type": "string"
},
"contributor_note": {
"type": "string"
}
}
}
},
"display_name": {
"type": "string"
},
"weeks_on_list": {
"type": "integer"
},
"published_date": {
"type": "string"
},
"rank_last_week": {
"type": "integer"
},
"bestsellers_date": {
"type": "string"
},
"amazon_product_url": {
"type": "string"
}
}
}
},
"copyright": {
"type": "string"
},
"num_results": {
"type": "integer"
},
"last_modified": {
"type": "string"
}
}
}
ListGetByDateResponse
{
"type": "object",
"properties": {
"status": {
"type": "string"
},
"results": {
"type": "object",
"properties": {
"books": {
"type": "array",
"items": {
"type": "object",
"properties": {
"rank": {
"type": "integer"
},
"isbns": {
"type": "array",
"items": {
"type": "object",
"properties": {
"isbn10": {
"type": "string"
},
"isbn13": {
"type": "string"
}
}
}
},
"price": {
"type": "integer"
},
"title": {
"type": "string"
},
"author": {
"type": "string"
},
"dagger": {
"type": "integer"
},
"asterisk": {
"type": "integer"
},
"age_group": {
"type": "string"
},
"publisher": {
"type": "string"
},
"book_image": {
"type": "string"
},
"contributor": {
"type": "string"
},
"description": {
"type": "string"
},
"weeks_on_list": {
"type": "integer"
},
"primary_isbn10": {
"type": "string"
},
"primary_isbn13": {
"type": "string"
},
"rank_last_week": {
"type": "integer"
},
"book_review_link": {
"type": "string"
},
"contributor_note": {
"type": "string"
},
"amazon_product_url": {
"type": "string"
},
"first_chapter_link": {
"type": "string"
},
"sunday_review_link": {
"type": "string"
},
"article_chapter_link": {
"type": "string"
}
}
}
},
"updated": {
"type": "string"
},
"list_name": {
"type": "string"
},
"corrections": {
"type": "array",
"items": {
"type": "object",
"properties": {}
}
},
"display_name": {
"type": "string"
},
"published_date": {
"type": "string"
},
"bestsellers_date": {
"type": "string"
},
"normal_list_ends_at": {
"type": "integer"
}
}
},
"copyright": {
"type": "string"
},
"num_results": {
"type": "integer"
},
"last_modified": {
"type": "string"
}
}
}
ListGetHistoryResponse
{
"type": "object",
"properties": {
"status": {
"type": "string"
},
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"isbns": {
"type": "array",
"items": {
"type": "object",
"properties": {
"isbn10": {
"type": "string"
},
"isbn13": {
"type": "string"
}
}
}
},
"price": {
"type": "integer"
},
"title": {
"type": "string"
},
"author": {
"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"
}
}
}
},
"age_group": {
"type": "string"
},
"publisher": {
"type": "string"
},
"contributor": {
"type": "string"
},
"description": {
"type": "string"
},
"ranks_history": {
"type": "array",
"items": {
"type": "object",
"properties": {
"rank": {
"type": "integer"
},
"dagger": {
"type": "integer"
},
"asterisk": {
"type": "integer"
},
"list_name": {
"type": "string"
},
"display_name": {
"type": "string"
},
"weeks_on_list": {
"type": "integer"
},
"primary_isbn10": {
"type": "string"
},
"primary_isbn13": {
"type": "string"
},
"published_date": {
"type": "string"
},
"ranks_last_week": {
"nullable": true
},
"bestsellers_date": {
"type": "string"
}
}
}
},
"contributor_note": {
"type": "string"
}
}
}
},
"copyright": {
"type": "string"
},
"num_results": {
"type": "integer"
}
}
}
ListGetNamesResponse
{
"type": "object",
"properties": {
"status": {
"type": "string"
},
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"updated": {
"enum": [
"WEEKLY",
"MONTHLY"
],
"type": "string"
},
"list_name": {
"type": "string"
},
"display_name": {
"type": "string"
},
"list_name_encoded": {
"type": "string"
},
"newest_published_date": {
"type": "string"
},
"oldest_published_date": {
"type": "string"
}
}
}
},
"copyright": {
"type": "string"
},
"num_results": {
"type": "integer"
}
}
}
OverviewResponse
{
"type": "object",
"properties": {
"status": {
"type": "string"
},
"results": {
"type": "object",
"properties": {
"lists": {
"type": "array",
"items": {
"type": "object",
"properties": {
"books": {
"type": "array",
"items": {
"type": "object",
"properties": {
"rank": {
"type": "integer"
},
"price": {
"type": "integer"
},
"title": {
"type": "string"
},
"author": {
"type": "string"
},
"age_group": {
"type": "string"
},
"publisher": {
"type": "string"
},
"contributor": {
"type": "string"
},
"description": {
"type": "string"
},
"created_date": {
"type": "string"
},
"updated_date": {
"type": "string"
},
"primary_isbn10": {
"type": "string"
},
"primary_isbn13": {
"type": "string"
},
"contributor_note": {
"type": "string"
}
}
}
},
"list_id": {
"type": "integer"
},
"updated": {
"type": "string"
},
"list_name": {
"type": "string"
},
"list_image": {
"type": "string"
},
"display_name": {
"type": "string"
}
}
}
},
"published_date": {
"type": "string"
},
"bestsellers_date": {
"type": "string"
}
}
},
"copyright": {
"type": "string"
},
"num_results": {
"type": "integer"
}
}
}
ReviewGetBookReviewsResponse
{
"type": "object",
"properties": {
"status": {
"type": "string"
},
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"url": {
"type": "string"
},
"byline": {
"type": "string"
},
"isbn13": {
"type": "array",
"items": {
"type": "string"
}
},
"summary": {
"type": "string"
},
"book_title": {
"type": "string"
},
"book_author": {
"type": "string"
},
"publication_dt": {
"type": "string"
}
}
}
},
"copyright": {
"type": "string"
},
"num_results": {
"type": "integer"
}
}
}