How to Get Goodreads Ratings via API

For book lovers who have a liking for a specific genre, they will probably check out a friend’s recommendation than follow any bestseller list. This is why Amazon’s Goodreads is a bookmarked site for avid readers. It’s a place where you can find an extensive database of books, recommendations and reviews by fellow book lovers.

Goodreads also provides an API for developers to access its data and further personalize it as per our application. Today we’ll see how to retrieve Goodreads book ratings through the Goodreads API using the ISBN or International Standard Book Number, which can later be used while displaying book information and such on your website.

To begin, either login or sign up with a name, email id and password to Goodreads and go to https://www.goodreads.com/api/keys (link). Enter any application name and company name and generate your API key. Then verify your account through the email received in the email id you entered.

Be sure to check out their Developer Terms of Service for the API. They also have a list of API methods in their API page, some of those methods will require OAuth authentication, the rest will only need the developer key, like the one we’ll look at in this post.

The response type of those methods vary, it’s either only in XML or JSON, or an option to chose between these two using the format parameter.

book.review_counts is a Goodreads API method that’ll fetch all the review stats for a list of book ISBNs. Its reponse type is JSON. The request URL is like this: https://www.goodreads.com/book/review_counts.json .

It takes four parameters:

  • key, which is the developer key
  • isbns – an array or single comma separated string of the ISBNs of the books that we want the review stats of
  • format – the format of the response (though in all honesty, I’m not really sure why this one exists, since the response is always going to be in JSON. Plans for future implementations?)
  • callback, the function that’ll wrap up the JSON response

Let’s take the two books; Head First Java, First edition (ISBN: 0596009208) and JavaScript: The Good Parts, 1st edition (ISBN: 0596517742) and get their review stats. The request URL is like this:

https://www.goodreads.com/book/review_counts.json?key={apikey}&isbns=0596009208,0596517742

And the responseText after beautification looks like this.

{"books":
    [ { "id":231262,
        "isbn":"0596009208",
        "isbn13":"9780596009205",
        "ratings_count":1842,
        "reviews_count":3599,
        "text_reviews_count":124,
        "work_ratings_count":2016,
        "work_reviews_count":3943,
        "work_text_reviews_count":136,
        "average_rating":"4.16"},
        
        { "id":2998152,
        "isbn":"0596517742",
        "isbn13":"9780596517748",
        "ratings_count":4430,
        "reviews_count":8921,
        "text_reviews_count":363,
        "work_ratings_count":4990,
        "work_reviews_count":9821,
        "work_text_reviews_count":381,
        "average_rating":"4.22"}
        ]}

If you want the rating of the Head First Java, First Edition book, it’s in myJSON.books[0].average_rating. The ratings_count and reviews_count keys in the objects represent the total number of ratings cast and reviews made for that particular edition of the book.

Similarly , text_reviews_count represents the total text-only reviews of the particular edition of the book. Whereas work_ratings_count, work_reviews_count and work_text_reviews_count represent the total ratings, reviews and text-only reviews of all the editions.

If you click on Rating Details of JavaScript: The Good Parts (1st Edition) in Goodreads it’ll display this.

goodreads

You can use all those extra review information if you’d like or just display a star rating for the book using the average_rating key value.

Note: According to the API documenation, “The Goodreads API gives you full access to Goodreads-owned meta-data, but it does not give you full access to book meta-data supplied by third parties such as Ingram. Book cover images, descriptions, and other data from third party sources might be excluded, because we do not have a license to distribute these data via our API.”

Once you’ve readied the book covers and descriptions, you can display the book info somewhat like below.

goodreads api