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

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)
http method: GET
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)
http method: GET
params:

• isbn: The isbn of the book to lookup.

• callback: function to wrap JSON response if format=json

• page: 1-N (default 1). The page number of reviews.

• user_id: USER_ID (required only for JSON)

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

• format: xml or 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)
http method: GET
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/show
url: http://www.goodreads.com/list/show/LIST_ID.xml   (sample url)
http method: GET
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
http method: POST
params:

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

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

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

Get the books on a members shelf. Customize the feed with the below variables.
url: http://www.goodreads.com/review/list?format=xml&v=2   (sample url)
http method: GET
params:

• v: 2

• key: Developer key (required).

• page: 1

• order: a, d

• shelf: read, currently-reading, to-read, etc

• sort: available_for_swap, position, votes, rating, shelves, avg_rating, isbn, comments, author, title, notes, cover, review, condition, date_started, random, date_read, year_pub, date_added, date_purchased, num_ratings, purchase_location, date_updated

• per_page: 1-200

• id: Goodreads id of the user

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
params:

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

• key: Developer key (required).

• id: id of the review

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?format=xml   (sample url)
http method: GET
params:

• user_id: id of the user

• key: Developer key (required).

• book_id: id of the book

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
http method: PUT
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)
http method: GET
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. This will search all books in the title/author/isbn fields and show matches, sorted by popularity on Goodreads.
url: http://www.goodreads.com/search/search   (sample url)
http method: GET
params:

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

• key: Developer key (required).

• page: Which page to return (default 1)

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

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
http method: POST
params:

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

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

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
http method: POST
params:

• name: Name of the new shelf

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
params:

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

• update: Type of update. Valid values are: books, reviews, statuses.

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)
http method: GET
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/friend/user?format=xml   (sample url)
http method: GET
params:

• page: 1-N (default 1)

• key: Developer key (required).

• sort: last_online|date_added|first_name

• id: Goodreads user_id (required unless using OAuth)

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
params:

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

• 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
http method: POST