goodreads_api_client

A lightweight wrapper around the Goodreads API

Quickstart Guide

Step-by-step instructions for getting started with goodreads_api_client.

Quickstart Guide

Eager to get started? This page gives a good introduction in how to get started with goodreads_api_client.

Installation

First, make sure you have goodreads_api_client installed:

$ pip install goodreads_api_client

Now let’s get started with a simple example.

Basic Usage

Make sure you have a Goodreads developer key first

Begin by importing the goodreads_api_client module:

>>> import goodreads_api_client as gr

Create a client:

>>> client = gr.Client(developer_key='<YOUR_DEVELOPER_KEY>')

Call the API:

>>> book = client.Book.show('1128434')

This will give you back an OrderedDict with the contents of the Goodreads API response, minus some generally useless request metadata. That means you could do a transformation like:

>>> keys_wanted = ['id', 'title', 'isbn']
>>> reduced_book = {k:v for k, v in book.items() if k in keys_wanted}
>>> reduced_book
{'id': '1128434', 'title': 'The Last Wish (The Witcher, #1)', 'isbn': '0575077832'}

Book is just one of many resources goodreads_api_client supports. For the full list, see Resources. For the methods available for a given resource, see the individual resource class.

Oauth Usage

Some Goodreads API endpoints are only available by using OAuth.

Begin by importing the goodreads_api_client module:

>>> import goodreads_api_client as gr

Create a client:

>>> client = gr.Client(developer_key='<YOUR_DEVELOPER_KEY>',
                       developer_secret='<YOUR_DEVELOPER_SECRET>')

Authorize the client (this will open up your browser if you have not authenticated against Goodreads before and stored your credentials):

>>> client.authorize()

Call the API:

>>> rec = client.Recommendation.show('25047806')

API Documentation

Documentation on specific functions, classes, and methods.

API Documentation

Goodreads API Client

Goodreads API Client is a non-official Python client for Goodreads <http://www.goodreads.com/>.

This part of the documentation covers the interfaces of goodreads_api_client.

Main Interface

You’ll primarily use goodreads_api_client via the Client it provides.

class goodreads_api_client.Client(developer_key: str, developer_secret: str = None, base_url: str = None)

Makes API Calls to the Goodreads API <https://goodreads.com/api>.

auth_user()

authorize()

search_author(name: str)

search_book(q: str, field: str = 'all', page: int = 1)

All other endpoints are provided through resource attributes on the Client

Resources

goodreads_api_client.resources

Holds classes for each Goodreads API Resource a user can interact with via the Goodreads API

class goodreads_api_client.resources.Author(transport=None)

Bases: goodreads_api_client.resources.base.Resource

books(id_: str)

List books for an author.

TODO: Add pagination support

resource_name = 'author'

show(id_: str)

class goodreads_api_client.resources.Book(transport=None)

Bases: goodreads_api_client.resources.base.Resource

id_to_work_id(ids: typing.Iterable[str])

isbn_to_id(isbns: typing.Iterable[str])

resource_name = 'book'

review_counts(isbns: typing.Iterable[str])

show(id_: str)

show_by_isbn(isbn: str)

title(title: str, author: str = None, rating: int = None)

class goodreads_api_client.resources.Comment(transport=None)

Bases: goodreads_api_client.resources.base.Resource

create()

list(id_: str, resource_type: str = 'review')

class goodreads_api_client.resources.Event(transport=None)

Bases: goodreads_api_client.resources.base.Resource

list(lat: str, lng: str, country_code: str, postal_code: str)

resource_name = 'event'

class goodreads_api_client.resources.Group(transport=None)

Bases: goodreads_api_client.resources.base.Resource

join()

list(user_id: str, sort: str = 'title')

members(id_: str, sort: str = 'first_name', q: str = None, page: int = 1)

resource_name = 'group'

search(q: str = None, page: int = 1)

show(id_: str)

class goodreads_api_client.resources.ReadStatus(transport=None)

Bases: goodreads_api_client.resources.base.Resource

resource_name = 'read_status'

show(id_: str)

class goodreads_api_client.resources.Recommendation(transport=None)

Bases: goodreads_api_client.resources.base.Resource

show(id_: str)

class goodreads_api_client.resources.Review(transport=None)

Bases: goodreads_api_client.resources.base.Resource

create()

destroy()

edit()

list()

recent_reviews()

resource_name = 'review'

show(id_: str)

show_by_user_and_book(user_id: str, book_id: str, include_review_on_work: bool = False)

class goodreads_api_client.resources.Series(transport=None)

Bases: goodreads_api_client.resources.base.Resource

list(author_id: str)

resource_name = 'series'

show(id_: str)

work(work_id: str)

class goodreads_api_client.resources.Shelf(transport=None)

Bases: goodreads_api_client.resources.base.Resource

add_books_to_shelves()

add_to_shelf()

list(user_id: str)

class goodreads_api_client.resources.Topic(transport=None)

Bases: goodreads_api_client.resources.base.Resource

create()

group_folder(id_: str)

resource_name = 'topic'

show(id_: str)

unread_group()

class goodreads_api_client.resources.User(transport=None)

Bases: goodreads_api_client.resources.base.Resource

compare()

followers()

following()

friends()

resource_name = 'user'

show(id_: str)

class goodreads_api_client.resources.UserStatus(transport=None)

Bases: goodreads_api_client.resources.base.Resource

create()

destroy()

index()

resource_name = 'user_status'

show(id_: str)

Lower-Level Classes

class goodreads_api_client.transport.Transport(developer_key: str, developer_secret: str = None, base_url: str = None)

Makes requests to Goodreads API and applies transform to response.

access_token_url

authorize()

authorize_url

gr

is_using_session() → bool

static read_credentials()

req(method: str = 'GET', endpoint: str = None, params: dict = None, data: dict = None, transform: str = 'xml', uses_oauth: bool = False)

request_token_url

session

Exceptions

goodreads_api_client.exceptions

Contains goodreads_api_client’s exceptions.

exception goodreads_api_client.exceptions.GoodreadsApiClientException

Bases: Exception

Base exception

exception goodreads_api_client.exceptions.OauthEndpointNotImplemented

Bases: goodreads_api_client.exceptions.GoodreadsApiClientException

OAuth not yet supported by this library

exception goodreads_api_client.exceptions.ExtraApiPermissionsRequired

Bases: goodreads_api_client.exceptions.GoodreadsApiClientException

Must contact Goodreads for extra perms to use endpoint

Contributor Guide

Guide to contributing to goodreads_api_client.

Contributor’s Guide

goodreads_api_client is under active development, and contributions are more than welcome!

1. See open issues on Github
2. Create a pull request against the master branch and tag @mdzhang for review
3. Once you get a :+1: and all CI checks are passing, go ahead and merge

Updating Tests

This library uses VCR for recording Goodreads API responses to use during tests. When adding new tests, you should add new API response recordings, aka cassettes. To record new cassettes, you’ll need

1. a Goodreads developer key
2. to put your keys into GOODREADS_API_KEY and GOODREADS_API_SECRET environment variables, using something like direnv
3. to blow away old cassettes (if necessary)
4. to re-run make test to re-record cassettes

For Oauth tests, you also want to

1. Run client.authorize() locally (e.g. from a Python REPL) to generate a client.json file

#. to uncomment the test patch blocking triggering the Oauth setup flow in <goodreads_api_client/tests/resources/conftest.py>, specifically the patch_transport.start() line # to re-run make test to re-record cassettes

And that should be it.

Code Linting

The CI is currently setup to lint all files, but you can also use Yelp’s pre-commit to run lint checks as pre-commit hooks