api

Welcome to the Goodreads API. If you have something you would like to build that isn't supported, please contact us — chances are good we will add your support. Some of the API methods will require you to register and get a developer key. Our write API uses OAuth for authorization. Learn more about how to use the API.

api methods

reviews.list   —   Get the books on a members shelf.
updates.friends   —   Get your friend updates.
search.best_book   —   Find a book by author or title.
search.authors   —   Find an author by name.
user.friends   —   Get a users friends.
shelves.user_shelves   —   Get a users book shelves.
search.email_lookup   —   Lookup a member by email address.
book.reviews   —   Get the reviews for a book given a Goodreads book id.
review.show   —   Get a user's review for a given book.
list.show   —   Get data about a listopia list.
book.reviews_by_isbn   —   Get the reviews for a book given an isbn.
book.reviews_by_title   —   Get the reviews for a book given a title string..
auth.user   —   Get id of user who authorized OAuth.
user_status.create   —   Update user status.
user_status.destroy   —   Delete user status.
review.update   —   Update book reviews.
review.create   —   Add review.
shelves.create   —   Add book shelf.
shelves.add_to_shelf   —   Add a book to a shelf.
quotes.create   —   Add a quote.
book links   —   how to build proper links to goodreads pages.
reviews widget   —   embed Goodreads book reviews on your site.

Get the books on a members shelf

Each shelf has an rss feed associated with it that gives the list of books on that shelf. Customize the feed with the below variables. No authentication is required.
url: http://www.goodreads.com/review/list_rss   (sample url)
params:
  • page: 1
  • order: a, d
  • per_page: 1-200
  • sort: position, votes, rating, shelves, avg_rating, isbn, comments, author, title, notes, cover, review, random, date_read, year_pub, date_added, num_ratings, date_updated
  • shelf: read, currently-reading, to-read, etc
  • key: Needed for private profiles. Different from developer key, and is unique to each member. Obtained from the member's rss link on the "my books page" or the lookup via email method.

Get your friend updates

Get your friend updates (the same data you see on your homepage) using the friend update RSS feed.
url: http://www.goodreads.com/home/index_rss   (sample url)
params:
  • key: A required parameter, and is different from your developer key - it is unique to each member.

Find a book by author or title

Get a xml file with the Goodreads url for the given book.
url: http://www.goodreads.com/api/book_url   (sample url)
params:

Find an author by name

Get an xml file with the Goodreads url for the given author name.
url: http://www.goodreads.com/api/author_url   (sample url)
params:

Get a users friends

Get an xml file with the given users friends.
url: http://www.goodreads.com/api/friends   (sample url)
params:
  • page: 1-N (default 1)
  • per_page: 1-100 (default 20)
  • id: Goodreads user_id (required)

Get a users book shelves

Get a xml file with the given users bookshelves.
url: http://www.goodreads.com/api/user_shelves   (sample url)
params:
  • page: 1-N (default 1)
  • per_page: 1-100 (default 20)
  • id: Goodreads user_id (required)

Lookup a member by email address

Get a xml file with the Goodreads user_id that can be used to link to a Goodreads profile. This is not a public method, please contact us to enable it.
url: http://www.goodreads.com/api/email_lookup   (sample url)
params:
  • email: Email address to lookup.

Get the reviews for a book given a Goodreads book id

Get an xml file that contains an excerpt (first 300 characters) of the most popular reviews of a book for a given internal Goodreads book_id. The reviews are from all known editions of the book.
url: http://www.goodreads.com/book/show   (sample url)
params:
  • page: 1-N (default 1). The page number of reviews.
  • id: A Goodreads internal book_id

Get a user's review for a given book

Get an xml file that contains the review and rating for the specified book and user
url: http://www.goodreads.com/review/show.xml   (sample url)
params:
  • user_id: id of the user
  • book_id: id of the book

Get data about a listopia list

xml version of list/show
url: http://www.goodreads.com/list/show/LIST_ID.xml   (sample url)
params:

Get the reviews for a book given an isbn

Get an xml file that contains an excerpt (first 300 characters) of the most popular reviews of a book for a given ISBN. The reviews are from all known editions of the book.
url: http://www.goodreads.com/book/isbn   (sample url)
params:
  • page: 1-N (default 1). The page number of reviews.
  • isbn: The isbn of the book to lookup.

Get the reviews for a book given a title string.

Get an xml file that contains an excerpt (first 300 characters) of the most popular reviews of a book for a given title/author. The book shown will be the most popular book that matches all the keywords in the input string. The reviews are from all known editions of the book.
url: http://www.goodreads.com/book/title   (sample url)
params:
  • title: The title/author of the book to lookup.
  • page: 1-N (default 1). The page number of reviews.

Get id of user who authorized OAuth

Get a xml file with the Goodreads user_id for the user who authorized access using OAuth. You'll need to register your app (required).
url: http://www.goodreads.com/api/auth_user

Update user status

Add status updates for members using OAuth. You'll need to register your app (required).
url: http://www.goodreads.com/user_status.xml
params:
  • user_status[book_id]: id of the book being reviewed
  • user_status[chapter]: chapter of book
  • user_status[page]: page of the book
  • user_status[body]: status update

Delete user status

Delete a status update for a member using OAuth. You'll need to register your app (required).
url: http://www.goodreads.com/user_status/1.xml

Update book reviews

Update book reviews for members using OAuth. You'll need to register your app (required). This method must be called with a PUT request and the final, numeric portion of the URL is the review ID.
url: http://www.goodreads.com/review/1212.xml
params:
  • review[review]: Text of the review
  • review[read_at]: Date (YYYY-MM-DD format, e.g. 2008-02-01)
  • review[rating]: Rating (1-5)

Add review

Add book reviews for members using OAuth. You'll need to register your app (required).
url: http://www.goodreads.com/review.xml
params:
  • review[review]: Text of the review
  • review[read_at]: Date (YYYY-MM-DD format, e.g. 2008-02-01)
  • book_id: Goodreads book_id (required)
  • review[rating]: Rating (1-5)

Add book shelf

Add book shelves for members using OAuth. You'll need to register your app (required).
url: http://www.goodreads.com/shelf.xml
params:
  • name: Name of the new shelf

Add a book to a shelf

Add a book to a shelf using OAuth. You'll need to register your app (required).
url: http://www.goodreads.com/shelf/add_to_shelf.xml
params:
  • book_id: id of the book to add to the shelf

Add a quote

Add a quote using OAuth. If you don't specify an author_id, it will try to look one up based on the author_name you provide. You'll need to register your app (required).
url: http://www.goodreads.com/quotes.xml
params:
  • quote[body]: The quote! (required)
  • quote[book_id]: id of the book from which the quote was taken
  • quote[author_id]: id of the author
  • quote[tags]: Comma-separated tags
  • quote[author_name]: Name of the quote author (required)
  • isbn: ISBN of the book from which the quote was taken. This will not override the book_id if it was provided


links


reviews about a book widget

This is a javascript widget designed for online book catalogues (booksellers, libraries, etc) that will display the most popular reviews given an isbn. The reviews are from all editions of the book. View the demo to see it in action. (requires developer key)

We also have some badges you can use with this widget to link back to Goodreads:


Goodreads-badge-add-16px Goodreads-badge-read-16px Goodreads-badge-add-nobg-16px Goodreads-badge-read-nobg-16px Goodreads-badge-add-38px Goodreads-badge-read-38px Goodreads-badge-add-black-38px Goodreads-badge-read-black-38px

developer key
api documentation
api terms
goodreads developer group (forums)
contact us
widgets



need help?


If you have any questions about our API, need some help getting started, or want to show off you've built then check out the developer forum. If you have something you would like to build that isn't supported, please contact us — chances are good we will add your support.