Goodreads API wrapper
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.

Goodreads Build Status

Ruby wrapper to communicate with Goodreads API.


  • Ruby 1.9.3+


Install gem with rubygems:

gem install goodreads

Or manually:

rake install

Getting Started

Before using Goodreads API you must create a new application. Visit signup form for details.

Setup client:

client = "KEY", api_secret: "SECRET")
client = "KEY") # short version

Global configuration

You can define client credentials on global level. Just create an initializer file (if using rails) under config/initializers:

  api_key: "KEY",
  api_secret: "SECRET"

Get global configuration:

Goodreads.configuration # => { api_key: "YOUR_KEY" }

In case you need to reset options:



Lookup books

You can lookup a book by ISBN, ID or Title:"id")
client.book_by_title("Book title")

Search for books (by title, isbn, genre):

search = client.search_books("The Lord Of The Rings") do |book|        # => book id
  book.title     # => book title


Look up an author by their Goodreads Author ID:

author ="id")              # => author id            # => author's name            # => link to author's Goodreads page
author.fans_count      # => number of fans author has on Goodreads
author.image_url       # => link to image of the author
author.small_image_url # => link to smaller of the author
author.about           # => description of the author
author.influences      # => list of links to author's influences
author.works_count     # => number of works by the author in Goodreads
author.gender          # => author's gender
author.hometown        # => author's hometown
author.born_at         # => author's birthdate
author.died_at         # => date of author's death

Look up an author by name:

author = client.author_by_name("Author Name")     # => author id   # => author name   # => link to author's Goodreads page


Pull recent reviews:

client.recent_reviews.each do |r|            # => review id    # => review book title
  r.body          # => review message     # => review user name

Get review details:

review ="id")         # => review id
review.user       # => user information       # => uook information
review.rating     # => user rating


Get the books on a user's shelf:

shelf = client.shelf(user_id, shelf_name)

shelf.books  # array of books on this shelf
shelf.start  # start index of this page of paginated results
shelf.end    # end index of this page of paginated results  # total number of books on this shelf


Get group details:

group ="id")                 # => group id
group.title              # => group title
group.access             # => group's access settings
                         # => (e.g., public or private)
group.group_users_count  # => number of users in the group

List the groups a given user is a member of:

group_list = client.group_list("user_id", "sort")         # => total number of groups  # => number of groups returned in the request

# Loop through the list to get details for each of the groups. do |g|                 # => group id
  g.access             # => access settings (private, public)
  g.users_count        # => number of members
  g.title              # => title
  g.image_url          # => url of the group's image
  g.last_activity_at   # => date and time of the group's last activity

The sort parameter is optional, and defaults to my_activity. For other sorting options, see here.


For API calls requiring permission, such as write operations or browsing friends, see our OAuth tutorial.


To run the test suite:

bundle exec rake test


You're welcome to submit patches and new features.

  • Create a new branch for your feature of bugfix
  • Add tests so it does not break any existing code
  • Open a new pull request
  • Check official API documentation


The MIT License (MIT)

Copyright (c) 2011-2018 Dan Sosedoff,