Goodreads thumb

An Introduction to the Goodreads APIs

GET going!

Building Your First GET:

Let's start using the Goodreads API with a simple GET query. First, you'll need to get your developer's key if you haven't already done so!

Our first use of the API will return a number, so we won't have to be dealing with JSON or XML parsing just yet. This web app will take an ISBN number (10) and return the Goodreads Book ID number. As you'll see from their API lists, many of your queries of their database will require use of their internal ID numbers. In order to start with an ISBN number, look up a favorite book's here so you'll know if you're on the right track:

Lookup an ISBN



Now that we have our developer's key, and our ISBN, let's try the simplest of queries by grabbing the specifics on our desired query from the Goodreads API site itself:

API 1

As we can see from this, we have an example link, the basis of our request to Goodreads's API: "https://www.goodreads.com/book/isbn_to_id". As it indicates, it's just a sample URL, if you follow this link, it will bring you back to the general site. Our actual code is going to look more like this:



GET 1

This is almost the simplest request of an API you can make! When you replace the key and a chosen ISBN with your values and run this, you will get an alert with the Goodreads Book ID. You can verify this by going to the chosen book in Goodreads and looking at the URL. You will see this ID number in the URL before the title as below:

GET 2

Another, simpler way to test GET requests is right in your browser! It's components are indicated with the base URL and the parameters in the method explanation:

  • Base sample URL,
  • Followed by a "?" to begin the GET request,
  • Then each parameter (in this case your developer's key) as a matched pair (here "key=" and value),separated by an "&" icon,
  • And ending with isbn in this case. Note with one isbn you must enter the singular isbn, matching the provided case!
  • NOTE: you'll need to experiment, as not all of these methods are detailed completely. Some leave off the key (it is always required), and some falsely indicate OAuth or leave it off. When in doubt, consult the Developer's Forum (see OAuth) at the end of this tutorial for more info!

You can post the assembled URL line (with your developer's key and ISBN in this case) right into the browser and you should get the response back:

GET 3

Now let's take another look at that code:

GET 1

After the initial variables holding your key and the ISBN, a new variable is opening an Ajax request (formerly an acronym for "Asynchronous JavaScript and XML" now often lowercase as frequently XML is not involved). This object (XMLHttpRequest) communicates with the server, sending and receiving information in a number of formats. In this case, we're just getting an integer back, but we'll follow up with JSON and XML formats, both of which are used with Goodreads.
We use this object to open our request, with the type ("GET") the URL, and a 'true' to indicate it is asynchronous (a 'false' here indicates it is synchronous, or we stop and wait until it is loaded).

As indicated in the comments, next we add a listener, which will run as soon as the object has loaded, (hence the asynchronous nature of the call). If we get a good response from the server, we will alert the number. Otherwise, the console will be logged the error response.

The line is the send of the request!

So, this is the most basic GET we can run, right? What use is this? Well, you might need a request like this within your script to get the Goodreads ID for any number of other requests. But let's step things up a bit. In our future calls, we're going to want to deal with a variety of data, not just numbers.



Ready to handle more data?

JSON & XML! »