As of December 8th 2020, Goodreads no longer issues new developer keys for our public developer API and plans to retire the current version of these tools. You can find more information here.
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:
Example Goodreads response:
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.
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](https://s.gr-assets.com/assets/api/example_oauth_approval-31590e62fbb4963585d6bb5df36e46b1.jpg)
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=https://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_tokenand
authorize. Goodreads will redirect the user to a URL that will look like this:
https://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.