api
Welcome to the Goodreads API. 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
auth.user —
Get id of user who authorized OAuth.
book.reviews —
Get the reviews for a book given a Goodreads book id.
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..
list.show —
Get data about a listopia list.
quotes.create —
Add a quote.
review.create —
Add review.
reviews.list —
Get the books on a members shelf.
review.show —
Get a user's review for a given book.
review.update —
Update book reviews.
search.authors —
Find an author by name.
search.books —
Find books by title, author, or isbn..
shelves.add_to_shelf —
Add a book to a shelf.
shelves.create —
Add book shelf.
updates.friends —
Get your friend updates.
user.show —
Get info about a member by id or username.
user.friends —
Get a user's friends.
user_status.create —
Update user status.
user_status.destroy —
Delete user status.
links & widgets
book links —
how to build proper links to Goodreads pages.
reviews widget —
embed Goodreads book reviews on your site.
api documentation
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
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.
- key: Developer key (required).
- id: A Goodreads internal book_id
Get the reviews for a book given an isbn
Get an xml or json 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.
- callback: function to wrap JSON response if format=json
- key: Developer key (required only for XML).
- format: xml or json
- isbn: The isbn of the book to lookup.
- user_id: USER_ID (required only for JSON)
example code for using json with callback:
<script type="text/javascript">
function myCallback(result) {
alert('nb of reviews for book: ' + result.reviews.length);
}
var scriptTag = document.createElement('script');
scriptTag.src = "http://www.goodreads.com/book/isbn?callback=myCallback&format=json&isbn=0441172717&user_id=USER_ID";
document.getElementsByTagName('head')[0].appendChild(scriptTag);
</script>
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:
- page: 1-N (default 1). The page number of reviews.
- key: Developer key (required).
- title: The title/author of the book to lookup.
Get data about a listopia list
xml version of list/showurl: http://www.goodreads.com/list/show/LIST_ID.xml (sample url)
params:
- key: Developer key (required).
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
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:
- shelf: read|currently-reading|to-read|<user shelf name> (must exist, see: shelves.user_shelves)
- 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)
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
- 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.
- 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
Get a user's review for a given book
Get an xml file that contains the review and rating for the specified book and userurl: http://www.goodreads.com/review/show.xml (sample url)
params:
- key: Developer key (required).
- book_id: id of the book
- user_id: id of the user
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:
- shelf: read|currently-reading|to-read|<user shelf name> (must exist, see: shelves.user_shelves)
- review[review]: Text of the review
- review[read_at]: Date (YYYY-MM-DD format, e.g. 2008-02-01)
- review[rating]: Rating (1-5)
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:
- key: Developer key (required).
Find books by title, author, or isbn.
Get an xml file with the most popular books for the given query.url: http://www.goodreads.com/search/search (sample url)
params:
- page: Which page to return (default 1)
- key: Developer key (required).
- q: Query string: title or author or isbn
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
- name: Name of the shelf (see: shelves.user_shelves)
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
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.
Get info about a member by id or username
Get an xml file with the public information about the given Goodreads user.url: http://www.goodreads.com/user/show (sample url)
params:
- key: Developer key (required).
- username: Goodreads user name (not first name). Usernames are optional on Goodreads.
- id: Goodreads user id.
Get a user's friends
Get an xml file with the given user's friends.url: http://www.goodreads.com/api/friends (sample url)
params:
- page: 1-N (default 1)
- key: Developer key (required).
- per_page: 1-100 (default 20)
- id: Goodreads user_id (required)
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/destroy/1.xml
links
- by isbn: http://www.goodreads.com/book/isbn/0590353403
- add a review: http://www.goodreads.com/review/isbn/0590353403
- by title: http://www.goodreads.com/book/title/Harry+Potter+and+the+Half-Blood+Prince
- by author: http://www.goodreads.com/book/author/Mark+Twain
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:
developer key
getting started
api terms
developer group (forums)
contact us
widgets
getting started
api terms
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 what 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.
