Client

GoodreadsClient

The GoodreadsClient is the wrapper that powers direct queries to the Goodreads API.

Fields

  • client_key: Application’s Goodreads API Client Key
  • client_secret: Application’s Goodreads API Client Secret

Properties

  • query_dict: A dict containing a GoodreadsClient’s client_key

Key Functions and Usage

Instantiate Client

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

author

Get information about an author, querying by Goodreads author id.

params:

  • author_id (int)

return: GoodreadsAuthor object

>>> author = gc.author(2618)
>>> author.name
u'Jonathan Safran Foer'

find_author

Get information about an author querying by name.

params:

  • author_name (string)

return: GoodreadsAuthor object or None

>>> author = gc.find_author("Stephen King")
>>> author.gid
'3389'

book

Get information about a book querying by Goodreads book id or ISBN.

params:

  • book_id (int) (optional)
  • book_isbn (int or string) (optional)

return: GoodreadsBook object

>>> book = gc.book(123)
>>> book.title
u'The Power of One (The Power of One, #1)'
>>> book.num_pages
'291'

search_books

Get the most popular books for a given query. Searches title, author, and genre.

params:

  • q (string)
  • page (int, deftault=1)
  • search_field (string, default=”all”)
    • valid options: [‘title’, ‘author’, ‘genre’, ‘all’]

return: List of GoodreadsBook objects.

return: list of matching GoodreadsBook objects

>>> books = gc.search_books("Shakespeare King")
>>> print(books)
[King Lear,
 Hamlet,
 Manga Shakespeare: King Lear,
 Macbeth,
 A Midsummer Night's Dream,
 Julius Caesar,
 The Merchant of Venice,
 Twelfth Night,
 King Henry IV, Part 1,
 Shakespeare's King Lear (Cliffs Notes),
 The Complete Works of Shakespeare,
 Richard III,
 Henry V,
 Prefaces to Shakespeare: King Lear,
 Four Great Tragedies: Hamlet / Othello / King Lear / Macbeth,
 The Winter's Tale,
 The Comedy of Errors,
 William Shakespeare, "King Lear",
 King Richard II (The Arden Shakespeare),
 Shakespeare's Ovid: Being Arthur Golding's Translation Of The Metamorphoses]

search_books_total_pages

Get the total number of pages for a book search. Accepts text for the query param and searches title, author, and genre.

params:

  • q (string)
  • page (int, default=1)
  • search_field (string, default=’all’)
    • valid options: [‘title’, ‘author’, ‘genre’, ‘all’]

return: integer number of results pages for the query string

>>> gc.search_books_total_pages("Shakespeare King")
41

search_books_all_pages

Get all the books for a given query. This will return all books where the title/author/genre fields show matches. Sorted by popularity on Goodreads. Note that if you use a broad search term this operation could take a while. Also bear in mind that the Goodreads API terms and conditions limit each application to 1 request/second per endpoint. This client function does not throttle requests.

params:

  • q (string)
  • page (int, default=1)
  • search_field (string, default=’all’)
    • valid options [‘title’, ‘author’, ‘genre’, ‘all’]

return: List of GoodreadsBook objects

>>> books = gc.search_books_all_pages("Demon in my View", search_field="title")
>>> print(books)
[Demon in My View,
 A Demon in My View,
 Demon in My View,
 Of a Demon in My View,
 Of a Demon in My View,
 A Demon in My View,
 The Tree of Hands / A Demon in My View,
 A Demon In My View,
 The face of trespass: A judgement in stone ; A demon in my view,
 A Demon in My View (Prose series) (Prose series),
 A Demon in My View (Prose Series 68),
 Novels by Amelia Atwater-Rhodes: Falcondance, Demon in My View, Hawksong, Wyvernhail, Snakecharm, Shattered Mirror, Midnight Predator,
 Nyeusigrube: The Kiesha'ra Series, Amelia Atwater-Rhodes, Demon in My View, Shattered Mirror, in the Forests of the Night,
 Articles on Nyeusigrube, Including: In the Forests of the Night, Demon in My View, Shattered Mirror, Midnight Predator, Hawksong, Snakecharm, Falcondance, Wyvernhail, Zane Cobriana, Amelia Atwater-Rhodes, the Kiesha'ra Series,
 The Ruth Rendell Omnibus: "Face of Trespass", "Judgement in Stone", "Demon in My View" v. 1]

group

Get information about a group. Queries the Goodreads API by group id.

params:

  • group_id (int or string)

return: GoodreadsGroup

>>> gc.group(8095)
u'Goodreads Developers'

owned_book

Get info about an owned book. Queries the Goodreads API by id. This method requires user authentication.

params:

  • owned_book_id (int or string)

return: GoodreadsOwnedBook object

find_groups

Find groups based based on a text query.

params:

  • query (string)
  • page (int, default=1)

return: List of OrderedDicts

request

create a GoodreadsRequest object and make a request to the Goodreads API.

user

Get information on a goodreads user, querying either by Goodreads id or username. Returns a GoodreadsUser object.

>>> user = gc.user(user_id=12345)
>>> user.name
u'Example McTesterson'

>>> user = gc.user(username="test_username")
>>> user.name
u'Test Name Person III'

GoodreadsClientException

An Exception that is raised when the GoodreadsClient encounters an error executing a request