Welcome to goodreads’ documentation!¶
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:
They can be installed using
sudo pip install -r requirements.txt
If you want to contribute to this package, you will need the
package as well.
To install, run the following command from the top-level package directory.
sudo python setup.py install
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.
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_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 = gc.book(1)
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.name u'J.K. Rowling' >>> book.average_rating u'4.49'
User data can be retrieved by user id or username.
>>> user = gc.user(1) >>> user.name u'Otis Chandler' >>> user.user_name u'otis' >>> user.small_image_url u'http://d.gr-assets.com/users/1189644957p2/1.jpg'
Let’s find a group discussing Python and get more information about it.
>>> g = gc.find_groups("Python") >>> g = groups >>> g['title'] u'The Computer Scientists' >>> group = gc.group(g['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 >>> event.title u'Books and Cocktails' >>> event.address u'120 N. Front St.' >>> event.city u'Wrightsville'
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.