An Introduction to the Goodreads APIs
The Goodreads API
An Example
Now let's demonstrate how you can leverage the Goodreads API to make your own search engine. Choose to search on either author, title or either using the pull-down, enter your search word and hit 'submit.' A table of results should form up beneath! You will see a list of the closest results from Goodreads's catalog, including the average Goodreads reader reviews. This is a simple example, but as we'll see soon, you can pull in far more data from their catalog as desired.
(Note: as a reminder -- don't forget you need to have the 'Allow-Control-Allow-Origin' feature enabled in Chrome for this to work due to CORS! See the introduction for more information.)
RESULTS WILL FORM BELOW
If they do not, be sure you are allowing CORS.
Goodreads Existing Documentation
Developer Terms of Service
While the Goodreads API is offered free of charge, you must agree to the terms of service before doing any work. I've listed a few points here relevant to this tutorial, but please open the link below to read it in its entirety before putting this into use on your own site.
- Not request any method more than once a second. Goodreads tracks all requests made by developers.
- Clearly display the Goodreads name or logo on any location where Goodreads data appears. For instance if you are displaying Goodreads reviews, they should either be in a section clearly titled "Goodreads Reviews", or each review should say "Goodreads review from John: 4 of 5 stars..."
- Not modify or change Goodreads data, including reviews, in any way. Reviews may be truncated for display purposes, but must link to the full review on Goodreads.
Getting a Development Key
At the time of this tutorial's creation, no part of using the Goodreads API is as well documented as the creation of developer key. A key is your signature in the requests you make to Goodreads -- it lets them know how many requests are being made per minute, to prevent errors from bogging down the system or abuse of the portal. You will need a key to take part in the tutorial, but it's incredibly simple to get one. Follow the link below, and once you have one, make note of it so we can get started! Note, you will also be given a secret key -- while we will not be using this in this tutorial, this key is needed to write to the Goodreads site through the API -- using a system called OAuth. We'll touch on this briefly at the end.
The APIs They Offer
Follow the link below to go to the full list of Goodreads's current API offerings. Note that these blurbs are your starting place for using the Goodreads API, but they are not infallible. During my tutorial work I stumbled on a few issues I had to solve (detailed later)! In other words, they're a necessary starting place, but don't hesitate to experiment!
Onward!
Okay, now that we've got all that out of the way, let's get you started making your very own request of the Goodreads API...