skip to navigation
skip to content

Goodreads 0.2.4

Python wrapper for Goodreads API

Latest Version: 0.3.2


This package provides a Python interface for the Goodreads API. Using it, you can do pretty much anything that Goodreads allows to do with their own data.


This package depends on the following packages:

  • xmltodict
  • requests
  • rauth

They can be installed using pip.

sudo pip install -r requirements.txt

If you want to contribute to this package, you will need the nose package as well.


To install, run the following command from the top-level package directory.

sudo python install

Getting Started

The first thing is to request an API key from Goodreads here. Once you have it, you can create a client instance to query Goodreads.

from goodreads import client
gc = client.GoodreadsClient(<api_key>, <api_secret>)

To access some of the methods, you need OAuth for authorization.

gc.authenticate(<access_token>, <access_token_secret>)

Note that access_token and access_token_secret are different from developer key and secret. For the development step, you can call the same function with no parameters to get authorization. It will open a URL pointing a Goodreads page for OAuth permission. For your application, you can direct the user to that particular URL, ask him/her to authorize your app and save the returning access_token and access_token_secret in your database.


This package provides a Python interface for most Goodreads API methods. Here are a few examples demonstrating how to access data on Goodreads.


Let’s access the first book added to Goodreads! It is the book with id 1.

book =

Once you have the GoodreadsBook instance for the book, you can access data for the queried book.

>>> book.title
u'Harry Potter and the Half-Blood Prince (Harry Potter, #6)'
>>> authors = book.authors
>>> authors[0].name
u'J.K. Rowling'
>>> book.average_rating


You can get information about an author as well.

>>> author =
u'Jonathan Safran Foer'
>>> author.works_count
>>> author.books
[Extremely Loud and Incredibly Close, Everything Is Illuminated, Eating Animals, Tree of Codes, Everything is Illuminated & Extremely Loud and Incredibly Close, The unabridged pocketbook of lightning, The Future Dictionary of America, A Convergence of Birds: Original Fiction and Poetry Inspired by Joseph Cornell, New American Haggadah, The Sixth Borough]


User data can be retrieved by user id or username.

>>> user = gc.user(1)
u'Otis Chandler'
>>> user.user_name
>>> user.small_image_url


Let’s find a group discussing Python and get more information about it.

>>> g = gc.find_groups("Python")
>>> g = groups[0]
>>> g['title']
u'The Computer Scientists'
>>> group =['id'])
>>> group.description
u'Only for Committed Self Learners and Computer Scientists Who are Starving for
Information, and Want to Advance their Skills Through: Reading, Practicing and
Discussion Computer Science and Programming Books.'


Goodreads API also allows to list events happening in an area.

>>> events = gc.list_events(21229)
>>> event = events[0]
>>> event.title
u'Books and Cocktails'
>>> event.address
u'120 N. Front St.'


Read more about this package here.


If you find an API method that is not supported by this package, feel free to create a Github issue. Also, you are more than welcome to submit a pull request for a bug fix or additional feature.


MIT License


Thanks to Paul Shannon for providing ‘goodreads’ package at PyPI.

File Type Py Version Uploaded on Size
goodreads-0.2.4.tar.gz (md5) Source 2015-05-06 9KB