Api Documentation

We've made accessing data from Goodreads easy – you can search books and authors on the site, access a member's book shelves, add book reviews, and more! You can view all the API methods or contact us if there's something you'd like to build that we don't currently support.

Getting Started

Some of our methods require a developer key, which you can get after you register. Most methods you can access just by passing your key, but some you'll need to use OAuth.

The easiest way to get started using our API is with curl. Just replace YOUR_KEY with your developer key in the example below:

curl "https://www.goodreads.com/search.xml?key=YOUR_KEY&q;=Ender%27s+Game"
Example Goodreads response:
<GoodreadsResponse>
<GoodreadsResponse>
  <Request>
    <!-- ... request metadata omitted ... -->
  </Request>
  <search>
    <query>
      <![CDATA[ Ender's Game ]]>
    </query>
    <results-start>1</results-start>
    <results-end>10</results-end>
    <total-results>100</total-results>
    <source>Goodreads</source>
    <query-time-seconds>0.10</query-time-seconds>
    <results>
      <work>
        <books_count type="integer">1</books_count>
        <id type="integer">11571577</id>
        <original_publication_day type="integer">30</original_publication_day>
        <original_publication_month type="integer">4</original_publication_month>
        <original_publication_year type="integer">2010</original_publication_year>
        <ratings_count type="integer">300</ratings_count>
        <text_reviews_count type="integer">16</text_reviews_count>
        <average_rating>4.17</average_rating>
        <best_book type="Book">
          <id type="integer">8782597</id>
          <title>Ender's Game</title>
          <author>
            <id type="integer">2940867</id>
            <name>Frederic P. Miller</name>
          </author>
          <image_url>
            https://s.gr-assets.com/assets/nophoto/book/111x148-6204a98ba2aba2d1aa07b9bea87124f8.png
          </image_url>
          <small_image_url>
            https://s.gr-assets.com/assets/nophoto/book/50x75-6121bf4c1f669098041843ec9650ca19.png
          </small_image_url>
        </best_book>
      </work>
      <!-- ... additional results omitted ... -->
    </results>
  </search>
</GoodreadsResponse>

Using Oauth

Writing data on Goodreads requires OAuth for authorization. To get started, you'll first need register your app.

OAuth is a simple way to allow third-party applications access to your data securly. It's based on existing standards and doesn't require you to give third-parties your username and password.

Learn more about OAuth.

Example User Flow

Once you've registered your app, you'll be able to request access on behalf of users to access their data using OAuth. Users will need to allow your application access from the Goodreads site. They'll be redirected to a page on Goodreads where they'll login in order to grant access. After allowing access they'll be redirected back to your site via the callback URL you provide us. At this point you'll be able to access their data using a token until they choose to revoke it.

Example oauth approval

Mobile Devices

If you are developing a mobile application, you'll want to use the mobile parameter when sending your users to the OAuth authorization screen. Example: /oauth/authorize?mobile=1 This parameter will render the sign in and authorize pages using the mobile layout which is optimized for smaller screen resolutions.

Callbacks

Want to know if your user grants or denies your application OAuth access? To find out, supply the oauth_callback parameter to your request like so: /oauth/authorize?oauth_callback=http://yourapp.com/goodreads_oauth_callback Goodreads will redirect the user to the oauth_callback URL your provide upon approval or denial of the oauth rights. The oauth_callback param value must not contain any query string params. Goodreads will append 2 query string parameters to give your app context. They are 
oauth_token
and 
authorize
. Goodreads will redirect the user to a URL that will look like this: http://yourapp.com/goodreads_oauth_callback?oauth_token=ezBHZc7C1SwvLGc646PEQ&authorize;=1 The oauth_token parameter is the token your app used to initiate the request and authorize tells you if the user accepted or declined access: 1 and 0, respectively. If the user declines oauth rights to your app the token is invalidated so its useless on future requests.

Example Code

You can check out a Ruby example of how this works. We'll be adding examples in PHP and Python soon.
back to api »
oauth example
© 2015 Goodreads Inc