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