Api

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
HTTP method: GET

Paginate an author's books

Get an xml file with a paginated list of an authors books.
URL: http://www.goodreads.com/author/list.xml    (sample url)
HTTP method: GET
Parameters:

• id: Goodreads Author id (required)

• page: 1-N (default 1)

• key: Developer key (required).

Get info about an author by id

Get an xml file with info about an author.
URL: http://www.goodreads.com/author/show.xml    (sample url)
HTTP method: GET
Parameters:

• id: Goodreads Author id.

• key: Developer key (required).

Get the Goodreads book ID given an ISBN

Get the Goodreads book ID given an ISBN. Response contains the ID without any markup.
URL: http://www.goodreads.com/book/isbn_to_id    (sample url)
HTTP method: GET
Parameters:

• isbn: The ISBN of the book to lookup.

• key: Developer key (required).

Get review statistics given a list of ISBNs

Get review statistics for books given a list of ISBNs. ISBNs can be specified as an array (e.g. isbns[]=0441172717&isbns[]=0141439602) or a single, comma-separated string (e.g. isbns=0441172717,0141439602). You can mix ISBN10s and ISBN13s, but you'll receive a 422 error if you don't specify any, and you'll receive a 404 if none are found.
URL: http://www.goodreads.com/book/review_counts.json    (sample url)
HTTP method: GET
Parameters:

• format: json

• isbns: Array of ISBNs or a comma seperated string of ISBNs (1000 ISBNs per request max.)

• callback: function to wrap JSON response

• key: Developer key (required).

Get the reviews for a book given a Goodreads book id

Get an xml file that contains embed code for the iframe reviews widget, shelves, and meta-data about the book. The reviews widget show 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.

It's important to note that the Goodreads API gives you full access to Goodreads-owned data. It does not give you full access to all book meta-data, such as images, descriptions, etc. Goodreads gets much of this data from 3rd party sources such as Amazon and Barnes & Noble, and we do not have a license to distribute this data via our API. You may easily sign up for a developer key at Amazon if you need book meta-data that Goodreads is not able to provide.
URL: http://www.goodreads.com/book/show?format=FORMAT    (sample url)
HTTP method: GET
Parameters:

• format: xml or json

• rating: Show only reviews with a particular rating (optional)

• text_only: Only show reviews that have text (default false)

• id: A Goodreads internal book_id

• key: Developer key (required).

Get the reviews for a book given an ISBN

Get an xml or json file that contains embed code for the iframe reviews widget that shows excerpts (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?format=FORMAT&isbn=ISBN    (sample url)
HTTP method: GET
Parameters:

• user_id: USER_ID (required only for JSON)

• isbn: The ISBN of the book to lookup.

• format: xml or json

• rating: Show only reviews with a particular rating (optional)

• key: Developer key (required only for XML).

• callback: function to wrap JSON response if format=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 embed code for the iframe reviews widget, which shows 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?format=FORMAT    (sample url)
HTTP method: GET
Parameters:

• format: xml or json

• rating: Show only reviews with a particular rating (optional)

• author: The author name of the book to lookup. This is optional, but is recommended for accuracy.

• title: The title of the book to lookup.

• key: Developer key (required).

Create a comment

Creates a new comment. You'll need to register your app (required).
URL: http://www.goodreads.com/comment.xml
HTTP method: POST
Parameters:

• comment[body]: This review was really insightful!

• id: Id of resource given as type param

• type: one of 'rating', 'poll', 'photo', 'comment', 'book_news_post', 'poll_vote', 'list', 'user_list_challenge', 'user_challenge', 'chapter', 'blog', 'author_blog_post', 'swap_request', 'quiz', 'librarian_note', 'interview', 'topic', 'review', 'fanship', 'user_list_vote', 'recommendation', 'owned_book', 'video', 'user_status', 'question_user_stat', 'question', 'event_response', 'user', 'recommendation_request', 'user_quote', 'quiz_score'

List comments on a subject

Lists comments
URL: http://www.goodreads.com/comment/index.xml    (sample url)
HTTP method: GET
Parameters:

• id: Id of resource given as type param

• page: 1-N (optional, default 1)

• type: one of 'rating', 'poll', 'photo', 'comment', 'book_news_post', 'poll_vote', 'list', 'user_list_challenge', 'user_challenge', 'chapter', 'blog', 'author_blog_post', 'swap_request', 'quiz', 'librarian_note', 'interview', 'topic', 'review', 'fanship', 'user_list_vote', 'recommendation', 'owned_book', 'video', 'user_status', 'question_user_stat', 'question', 'event_response', 'user', 'recommendation_request', 'user_quote', 'quiz_score'

Events in your area

Shows events nearby the authenticating user or you can get a list of events near a location by passing lat/lng coordinates
URL: http://www.goodreads.com/event/index.xml    (sample url)
HTTP method: GET
Parameters:

• lat: Latitude (optional)

• lng: Longitude (optional)

• key: Developer key (required).

Follow a user

Start following a user using OAuth. You'll need to You'll need to register your app (required).
URL: http://www.goodreads.com/user/<user_id>/followers?format=xml
HTTP method: POST
Parameters:

• id: Goodreads user id of user to follow

Add a friend

Sends a friend request to a user using OAuth. You'll need to register your app (required).
URL: http://www.goodreads.com/friend/add_as_friend.xml
HTTP method: POST
Parameters:

• id: Goodreads user id for friend

List groups for a given user

Returns xml list of groups the user specified by id belongs to
URL: http://www.goodreads.com/group/list/<user_id>.xml    (sample url)
HTTP method: GET
Parameters:

• sort: One of 'title', 'last_activity', 'my_activity', 'members' ('members' will sort by number of members in the group)

• key: Developer key (required).

Return members of a particular group

Returns an XML list of members of the group
URL: http://www.goodreads.com/group/members/<group_id>.xml    (sample url)
HTTP method: GET
Parameters:

• q: List of names to search for, separating each name with a space character. Optional, will find all members by default

• sort: One of 'num_comments', 'num_books', 'date_joined', 'last_online', 'first_name'

• page: Which page of results to show (default 1)

• key: Developer key (required).

Get info about a group by id

XML version of group/show
URL: http://www.goodreads.com/group/show/<group_id>.xml    (sample url)
HTTP method: GET
Parameters:

• sort: Field to sort topics by. One of 'title', 'updated_at', 'views', 'comments_count'

• order: 'a' for ascending, 'd' for descending

• key: Developer key (required).

Get the listopia lists for a given book

XML version of list/book. This API requires extra permission please contact us
URL: http://www.goodreads.com/list/book/<book_id>.xml    (sample url)
HTTP method: GET
Parameters:

• key: Developer key (required).

Get the books from a listopia list. This API requires extra permission please contact us

XML version of list/show
URL: http://www.goodreads.com/list/show/<list_id>.xml    (sample url)
HTTP method: GET
Parameters:

• key: Developer key (required).

Get the listopia lists for a given tag. This API requires extra permission please contact us

XML version of list/tag
URL: http://www.goodreads.com/list/tag/tag_name.xml    (sample url)
HTTP method: GET
Parameters:

• key: Developer key (required).

See the current user's notifications

Viewing any new notifications here will mark them as 'viewed'. using OAuth
URL: /notifications.xml    (sample url)
HTTP method: GET
Parameters:

• page: page number (optional, default 1)

Add to books owned

Adds a book to user's list of owned books using OAuth. You'll need to register your app (required).
URL: http://www.goodreads.com/owned_books.xml
HTTP method: POST
Parameters:

• owned_book[condition_code]: one of 10 (brand new), 20 (like new), 30 (very good), 40 (good), 50 (acceptable), 60 (poor)

• owned_book[unique_code]: BookCrossing id (BCID)

• owned_book[original_purchase_location]: where this book was purchased

• owned_book[book_id]: id of the book (required)

• owned_book[original_purchase_date]: when book was purchased

• owned_book[condition_description]: description of book's condition

• owned_book[available_for_swap]: true or false, if book is available for swap

List books owned by a user

Get an xml file with a list of owned books using OAuth. You'll need to register your app (required).
URL: http://www.goodreads.com/owned_books/user?format=xml    (sample url)
HTTP method: GET
Parameters:

• id: Goodreads user_id

• page: 1-N (optional, default 1)

Show an owned book

Get an xml file describing an owned book using OAuth, including the current owner's user id (current_owner_id), it's BookCrossing ID (bcid), number of times traded, etc. You'll need to register your app (required).
URL: http://www.goodreads.com/owned_books/<id>.xml
HTTP method: GET

Update an owned book

Updates a book a user owns using OAuth. You'll need to register your app (required).
URL: http://www.goodreads.com/owned_books/<id>.xml
HTTP method: PUT
Parameters:

• owned_book[condition_code]: one of 10 (brand new), 20 (like new), 30 (very good), 40 (good), 50 (acceptable), 60 (poor), (optional)

• owned_book[unique_code]: BookCrossing id (BCID) (optional)

• owned_book[original_purchase_location]: where this book was purchased (optional)

• owned_book[book_id]: id of the book (required)

• owned_book[original_purchase_date]: when book was purchased (optional)

• id: id of the owned book record

• owned_book[condition_description]: description of book's condition (optional)

• owned_book[available_for_swap]: true or false, if book is available for swap (optional, default false)

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
HTTP method: POST
Parameters:

• quote[body]: The quote! (required)

• isbn: ISBN of the book from which the quote was taken. This will not override the book_id if it was provided

• 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)

Rate a review

Rate a review (like or dislike) using OAuth. You'll need to register your app (required).
URL: http://www.goodreads.com/rating/new_review?format=xml
HTTP method: POST
Parameters:

• rating: 1 (like) or 0 (unlike)

• resource_id: id of the review to rate

Add review

Add book reviews for members using OAuth. You'll need to register your app (required).
URL: http://www.goodreads.com/review.xml
HTTP method: POST
Parameters:

• shelf: read|currently-reading|to-read|<user shelf name> (must exist, see: shelves.user_shelves) (optional, default 'read')

• review[review]: Text of the review (optional)

• review[read_at]: Date (YYYY-MM-DD format, e.g. 2008-02-01) (optional)

• book_id: Goodreads book_id (required)

• review[rating]: Rating (0-5) (optional, default is 0 (No rating))

Destroy a review

Delete book reviews for members using OAuth. You'll need to register your app (required).
URL: /review/destroy.xml
HTTP method: POST
Parameters:

• book_id: Goodreads book_id (required)

Get the books on a members shelf

Get the books on a members shelf. Customize the feed with the below variables. Viewing members with profiles who have set them as visible to members only or just their friends requires using OAuth.
URL: http://www.goodreads.com/review/list.xml?v=2    (sample url)
HTTP method: GET
Parameters:

• per_page: 1-200 (optional)

• v: 2

• shelf: read, currently-reading, to-read, etc. (optional)

• sort: available_for_swap, position, num_pages, votes, recommender, rating, shelves, format, avg_rating, date_pub, isbn, comments, author, title, notes, cover, isbn13, review, date_pub_edition, condition, asin, date_started, owned, random, date_read, year_pub, read_count, date_added, date_purchased, num_ratings, purchase_location, date_updated (optional)

• order: a, d (optional)

• id: Goodreads id of the user

• page: 1-N (optional)

• key: Developer key (required).

• search[query]: query text to match against member's books (optional)

Recent reviews from all members.

Get an xml file with the most recently added reviews from all members.
URL: http://www.goodreads.com/review/recent_reviews.xml    (sample url)
HTTP method: GET
Parameters:

• key: Developer key (required).

Get a review

Get an xml file that contains the review and rating
URL: http://www.goodreads.com/review/show.xml    (sample url)
HTTP method: GET
Parameters:

• id: id of the review

• page: 1-N. The page number of comments. (default 1, optional)

• key: Developer key (required).

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_by_user_and_book.xml    (sample url)
HTTP method: GET
Parameters:

• user_id: id of the user

• book_id: id of the book

• include_review_on_work: 'true' or 'false' indicating whether to return a review for another book in the same work if review not found for the specified book (default 'false', optional)

• key: Developer key (required).

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/<ID>.xml
HTTP method: PUT
Parameters:

• shelf: read|currently-reading|to-read|<user shelf name> (optional, must exist, see: shelves.user_shelves)

• review[review]: Text of the review (optional)

• review[read_at]: Date (optional, YYYY-MM-DD format, e.g. 2008-02-01)

• review[rating]: Rating (0-5) (optional, 0 means no rating)

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.xml    (sample url)
HTTP method: GET
Parameters:

• key: Developer key (required).

Find books by title, author, or ISBN

Get an xml file with the most popular books for the given query. This will search all books in the title/author/ISBN fields and show matches, sorted by popularity on Goodreads. There will be cases where a result is shown on the Goodreads site, but not through the API. This happens when the result is an Amazon-only edition and we have to honor Amazon's terms of service.
URL: http://www.goodreads.com/search/index.xml    (sample url)
HTTP method: GET
Parameters:

• search[field]: Field to search, one of title, author, or genre (default is all)

• q: The query text to match against book title, author, and ISBN fields. Supports boolean operators and phrase searching.

• page: Which page to return (default 1, optional)

• key: Developer key (required).

See a series

Info on a series
URL: /series/<id>.xml    (sample url)
HTTP method: GET

See all series by an author

List of all series by an author
URL: /series/list/<author_id>.xml    (sample url)
HTTP method: GET

See all series a work is in

List of all series a work is in
URL: /work/<work_id>/series?format=xml    (sample url)
HTTP method: GET

Add a book to a shelf

Add a book to a shelf using OAuth. This method can also be used to remove from shelf. You'll need to register your app (required).
URL: http://www.goodreads.com/shelf/add_to_shelf.xml
HTTP method: POST
Parameters:

• name: Name of the shelf (see: shelves.user_shelves)

• book_id: id of the book to add to the shelf

• a: Leave this blank unless you're removing from a shelf. If removing, set this to 'remove'. (optional)

Get a user's shelves

Lists shelves for a user
URL: http://www.goodreads.com/shelf/list.xml    (sample url)
HTTP method: GET
Parameters:

• user_id: Goodreads user id

• page: 1-N (default 1)

• key: Developer key (required).

Create a new topic via OAuth

Create a new topic using OAuth. You'll need to register your app (required).
URL: http://www.goodreads.com/topic.xml
HTTP method: POST
Parameters:

• digest: Indicates whether the user would like to receive an email when someone replies to the topic (user will get one email only). To enable, set to 'on'; otherwise, default is not to add to update feed

• topic[title]: Title for the topic (required)

• topic[question_flag]: Indicates whether the topic is a discussion question ('1') or not ('0'). Default is 0 (non-question)

• update_feed: Indicates whether the comment for the new topic should be added to the user's update feed. To enable, set to 'on'; otherwise, default is not to add to update feed

• comment[body_usertext]: The text of the comment that starts the topic thread. Can include Goodreads book/author tags of the form [book:Title|ID] (required)

• topic[folder_id]: If the subject is a group, you can supply a folder id to add the topic to. Be sure that the folder belongs to the group. By default, if the subject_type is 'Group', then the topic will be added to the 'general' folder

• topic[subject_type]: Either 'Book' or 'Group'. If 'Book', the book the topic is about. If 'Group', the group that the topic belongs to. (required)

• topic[subject_id]: The id for the subject the topic belongs to, either book_id or group_id, as appropriate (required)

Get list of topics in a group's folder

Returns a list of topics in a group's folder specified either by folder id or by group id.
URL: http://www.goodreads.com/topic/group_folder/<folder_id>.xml    (sample url)
HTTP method: GET
Parameters:

• sort: One of 'title', 'updated_at', 'views', 'comments_count'

• order: 'a' for ascending, 'd' for descending

• page: Page in results to show, 1-N (default 1)

• group_id: If supplied and id is set to 0, then will return topics from the general folder for the group indicated by group_id. If id is non-zero, this param is ignored. Note: may return 404 if there are no topics in the general folder for the specified group

• key: Developer key (required).

Get info about a topic by id

XML version of topic/show
URL: http://www.goodreads.com/topic/show/<topic_id>.xml    (sample url)
HTTP method: GET
Parameters:

• key: Developer key (required).

Get a list of topics with unread comments

Get a list of topics from a specified group that have comments added since the last time the user viewed the topic using OAuth. You'll need to register your app (required).
URL: http://www.goodreads.com/topic/unread_group/<group_id>.xml    (sample url)
HTTP method: GET
Parameters:

• viewed: Indicates whether to show topics user has viewed before or not. Default is to include all topics; set this param to 'true' or '1' to restrict to only topics the user has already viewed

• sort: One of 'title', 'updated_at', 'views', 'comments_count'

• order: 'a' for ascending, 'd' for descending

• page: Page in results to show, 1-N (default 1)

Get your friend updates

Get your friend updates (the same data you see on your homepage) using OAuth. You'll need to register your app (required).
URL: http://www.goodreads.com/updates/friends.xml
HTTP method: GET
Parameters:

• max_updates: The max limit of updates. (optional)

• update_filter: Which updates to show. Options are: friends (default - includes followers), following, top_friends. (optional)

• update: Type of update. Valid values are: books, reviews, statuses. (optional, default all)

Add book shelf

Add book shelves for members using OAuth. You'll need to register your app (required).
URL: http://www.goodreads.com/user_shelves.xml
HTTP method: POST
Parameters:

• user_shelf[featured]: 'true' or 'false' (optional, default false)

• user_shelf[exclusive_flag]: 'true' or 'false' (optional, default false)

• user_shelf[name]: Name of the new shelf

• user_shelf[sortable_flag]: 'true' or 'false' (optional, default false)

Delete book shelf

Delete a shelf using OAuth. You'll need to register your app (required).
URL: http://www.goodreads.com/user_shelves/%5BUSER_SHELF_ID%5D.xml
HTTP method: DELETE

Edit book shelf

Edit a shelf using OAuth. You'll need to register your app (required).
URL: http://www.goodreads.com/user_shelves/%5BUSER_SHELF_ID%5D.xml
HTTP method: PUT
Parameters:

• user_shelf[featured]: 'true' or 'false' (optional, default false)

• user_shelf[exclusive_flag]: 'true' or 'false' (optional, default false)

• user_shelf[name]: Name of the new shelf

• user_shelf[sortable_flag]: 'true' or 'false' (optional, default false)

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.xml    (sample url)
HTTP method: GET
Parameters:

• username: Goodreads user name (not first name). Usernames are optional on Goodreads.

• id: Goodreads user id.

• key: Developer key (required).

Compare books with another member

Get an xml file with stats comparing your books to another member's using OAuth. You'll need to register your app (required).
URL: http://www.goodreads.com/user/compare/1.xml
HTTP method: GET
Parameters:

• id: Goodreads user_id you want to compare books to

Get a user's followers

Get an xml file with the given user's followers.
URL: http://www.goodreads.com/user/<user_id>/followers.xml    (sample url)
HTTP method: GET
Parameters:

• id: Goodreads user_id

• page: 1-N (optional, default 1)

• key: Developer key (required).

Get people a user is following

Get an xml file with people the given user is following.
URL: http://www.goodreads.com/user/<user_id>/following?format=xml    (sample url)
HTTP method: GET
Parameters:

• id: Goodreads user_id

• page: 1-N (optional, default 1)

• key: Developer key (required).

Get a user's friends

Get an xml file with the given user's friends using OAuth.
URL: http://www.goodreads.com/friend/user.xml    (sample url)
HTTP method: GET
Parameters:

• sort: last_online|date_added|first_name (optional)

• id: Goodreads user_id (required)

• page: 1-N (optional, default 1)

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
HTTP method: POST
Parameters:

• user_status[percent]: percent complete (use instead of page if appropriate)

• user_status[book_id]: id of the book being reviewed (optional)

• user_status[page]: page of the book (optional)

• user_status[body]: status update (required, unless page or percent is present, then it is optional)

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
HTTP method: POST

View user status

Views most recent user statuses on the site.
URL: http://www.goodreads.com/user_status/index.xml
HTTP method: GET

See all editions by work

List of all the available editions of a particular work. This API requires extra permission please contact us
URL: /work/editions/<work_id>.xml    (sample url)
HTTP method: GET
Parameters:

• key: Developer key (required).

• 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