CloudObjects / Directory / The New York Times / Books API
Sign in

Books API

a wa:WebAPI in The New York Times

The Books API provides information about book reviews and The New York Times bestsellers lists.

Base URL

The API endpoint is located at the following URL:
https://api.nytimes.com/svc/books/v3

Authentication

No authentication methods were specified. Please contact the API provider to get this information!

API Methods

These are the methods supported by the API:

  • GET /lists/best-sellers/history.json Best Seller History List

    Optional parameters:
    age-group The target age group for the best seller.
    author 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 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 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).
    price The publisher's list price of the best seller, including decimal point
    publisher The standardized name of the publisher
    title The title of the best seller When searching, you can specify a portion of a title or a full title.
    Success response:

    Status Code 200
    
    
  • GET /lists.{format} Best Seller List

    Required parameters:
    format -
    Optional parameters:
    list 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.)
    weeks-on-list The number of weeks that the best seller has been on list-name, as of bestsellers-date
    bestsellers-date 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).
    date YYYY-MM-DD The date the best-seller list was published on NYTimes.com (compare bestsellers-date)
    isbn International Standard Book Number, 10 or 13 digits
    published-date YYYY-MM-DD The date the best-seller list was published on NYTimes.com (compare bestsellers-date)
    rank The rank of the best seller on list-name as of bestsellers-date
    rank-last-week The rank of the best seller on list-name one week prior to bestsellers-date
    offset Sets the starting point of the result set
    sort-order Sets the sort order of the result set
    Success response:

    Status Code 200
    
    
  • GET /lists/{date}/{list}.json Best Seller List by Date

    Required parameters:
    date -
    list Name of the Best Sellers List. You can get the full list from /lists/names.json
    Optional parameters:
    isbn International Standard Book Number, 10 or 13 digits
    list-name 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.)
    published-date YYYY-MM-DD The date the best-seller list was published on NYTimes.com (compare bestsellers-date)
    bestsellers-date 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).
    weeks-on-list The number of weeks that the best seller has been on list-name, as of bestsellers-date
    rank The rank of the best seller on list-name as of bestsellers-date
    rank-last-week The rank of the best seller on list-name one week prior to bestsellers-date
    offset Sets the starting point of the result set
    sort-order The default is ASC (ascending). The sort-order parameter is used with the sort-by parameter — for details, see each request type.
    Success response:

    Status Code 200
    
    
  • GET /lists/overview.{format} Best Seller List Overview

    Required parameters:
    format -
    Optional parameters:
    published_date 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.
    api-key -
    Success response:

    Status Code 200
    
    
  • GET /lists/names.{format} Best Seller List Names

    Required parameters:
    format -
    Optional parameters:
    api-key -
    Success response:

    Status Code 200
    
    
  • GET /reviews.{format} Reviews

    Required parameters:
    format -
    Optional parameters:
    isbn Searching by ISBN is the recommended method. You can enter 10- or 13-digit ISBNs.
    title You’ll need to enter the full title of the book. Spaces in the title will be converted into the characters %20.
    author 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.
    api-key -
    Success response:

    Status Code 200
    
    
Meta
URI / COID
coid://nytimes.cloudobjects.io/BooksAPI/V3
Revision
2-9c69f0c3e24952d903f3a1e46a999676
Last updated
2017-05-29 15:26 (UTC)
Created at
2017-12-11 07:40 (UTC)
Usage permission
co:Public