Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Goodreads API wrapper
Ruby
Branch: master

README.md

Goodreads Build Status

Ruby wrapper to communicate with Goodreads API.

Requirements

  • Ruby 1.9.3+

Installation

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 = Goodreads::Client.new(:api_key => 'KEY', :api_secret => 'SECRET')
client = Goodreads.new(:api_key => 'KEY') # short version

Global configuration

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

Goodreads.configure(
  :api_key => 'KEY',
  :api_secret => 'SECRET'
)

Get global configuration:

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

In case you need to reset options:

Goodreads.reset_configuration

Examples

Lookup books

You can lookup a book by ISBN, ID or Title:

client.book('id')
client.book_by_isbn('ISBN')
client.book_by_title('Book title')

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

search = client.search_books('The Lord Of The Rings')

search.results.work.each do |book|
  book.id        # => book id
  book.title     # => book title
end

Authors

Look up an author by their Goodreads Author ID:

author = client.author('id')

author.id              # => author id
author.name            # => author's name
author.link            # => 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 id
author.name   # => author name
author.link   # => link to author's Goodreads page

Reviews

Pull recent reviews:

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

Get review details:

review = client.review('id')

review.id         # => review id
review.user       # => user information
review.book       # => uook information
review.rating     # => user rating

Shelves

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
shelf.total  # total number of books on this shelf

Groups

Get group details:

group = client.group('id')

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')

group_list.total         # => total number of groups
group_list.group.count  # => number of groups returned in the request

# Loop through the list to get details for each of the groups.

group_list.group.each do |g|
  g.id                 # => 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
end

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

OAuth

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

Testing

To run the test suite:

bundle exec rake test

Contributions

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

License

The MIT License (MIT)

Copyright (c) 2011-2015 Dan Sosedoff, dan.sosedoff@gmail.com

Something went wrong with that request. Please try again.