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)[source]¶

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

auth_user()[source]¶

authorize()[source]¶

search_author(name: str)[source]¶

search_book(q: str, field: str = 'all', page: int = 1)[source]¶

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)[source]¶

Bases: goodreads_api_client.resources.base.Resource

books(id_: str)[source]¶

List books for an author.

TODO: Add pagination support

resource_name = 'author'¶

show(id_: str)[source]¶

class goodreads_api_client.resources.Book(transport=None)[source]¶

Bases: goodreads_api_client.resources.base.Resource

id_to_work_id(ids: typing.Iterable[str])[source]¶

isbn_to_id(isbns: typing.Iterable[str])[source]¶

resource_name = 'book'¶

review_counts(isbns: typing.Iterable[str])[source]¶

show(id_: str)[source]¶

show_by_isbn(isbn: str)[source]¶

title(title: str, author: str = None, rating: int = None)[source]¶

class goodreads_api_client.resources.Comment(transport=None)[source]¶

Bases: goodreads_api_client.resources.base.Resource

create()[source]¶

list(id_: str, resource_type: str = 'review')[source]¶

class goodreads_api_client.resources.Event(transport=None)[source]¶

Bases: goodreads_api_client.resources.base.Resource

list(lat: str, lng: str, country_code: str, postal_code: str)[source]¶

resource_name = 'event'¶

class goodreads_api_client.resources.Group(transport=None)[source]¶

Bases: goodreads_api_client.resources.base.Resource

join()[source]¶

list(user_id: str, sort: str = 'title')[source]¶

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

resource_name = 'group'¶

search(q: str = None, page: int = 1)[source]¶

show(id_: str)[source]¶

class goodreads_api_client.resources.ReadStatus(transport=None)[source]¶

Bases: goodreads_api_client.resources.base.Resource

resource_name = 'read_status'¶

show(id_: str)[source]¶

class goodreads_api_client.resources.Recommendation(transport=None)[source]¶

Bases: goodreads_api_client.resources.base.Resource

show(id_: str)[source]¶

class goodreads_api_client.resources.Review(transport=None)[source]¶

Bases: goodreads_api_client.resources.base.Resource

create()[source]¶

destroy()[source]¶

edit()[source]¶

list()[source]¶

recent_reviews()[source]¶

resource_name = 'review'¶

show(id_: str)[source]¶

show_by_user_and_book(user_id: str, book_id: str, include_review_on_work: bool = False)[source]¶

class goodreads_api_client.resources.Series(transport=None)[source]¶

Bases: goodreads_api_client.resources.base.Resource

list(author_id: str)[source]¶

resource_name = 'series'¶

show(id_: str)[source]¶

work(work_id: str)[source]¶

class goodreads_api_client.resources.Shelf(transport=None)[source]¶

Bases: goodreads_api_client.resources.base.Resource

add_books_to_shelves()[source]¶

add_to_shelf()[source]¶

list(user_id: str)[source]¶

class goodreads_api_client.resources.Topic(transport=None)[source]¶

Bases: goodreads_api_client.resources.base.Resource

create()[source]¶

group_folder(id_: str)[source]¶

resource_name = 'topic'¶

show(id_: str)[source]¶

unread_group()[source]¶

class goodreads_api_client.resources.User(transport=None)[source]¶

Bases: goodreads_api_client.resources.base.Resource

compare()[source]¶

followers()[source]¶

following()[source]¶

friends()[source]¶

resource_name = 'user'¶

show(id_: str)[source]¶

class goodreads_api_client.resources.UserStatus(transport=None)[source]¶

Bases: goodreads_api_client.resources.base.Resource

create()[source]¶

destroy()[source]¶

index()[source]¶

resource_name = 'user_status'¶

show(id_: str)[source]¶

Lower-Level Classes¶

class goodreads_api_client.transport.Transport(developer_key: str, developer_secret: str = None, base_url: str = None)[source]¶

Makes requests to Goodreads API and applies transform to response.

access_token_url¶

authorize()[source]¶

authorize_url¶

gr¶

is_using_session() → bool[source]¶

static read_credentials()[source]¶

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

request_token_url¶

session¶

Exceptions¶

goodreads_api_client.exceptions¶

Contains goodreads_api_client’s exceptions.

exception goodreads_api_client.exceptions.GoodreadsApiClientException[source]¶

Bases: Exception

Base exception

exception goodreads_api_client.exceptions.OauthEndpointNotImplemented[source]¶

Bases: goodreads_api_client.exceptions.GoodreadsApiClientException

OAuth not yet supported by this library

exception goodreads_api_client.exceptions.ExtraApiPermissionsRequired[source]¶

Bases: goodreads_api_client.exceptions.GoodreadsApiClientException

Must contact Goodreads for extra perms to use endpoint