# Goodreads [![Build Status](https://img.shields.io/travis/sosedoff/goodreads/master.svg)](http://travis-ci.org/sosedoff/goodreads)

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](http://www.goodreads.com/api/keys) for details.

Setup client:

``` ruby
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`:

``` ruby
Goodreads.configure(
  api_key: "KEY",
  api_secret: "SECRET"
)
```

Get global configuration:

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

In case you need to reset options:

```ruby
Goodreads.reset_configuration
```

## Examples

### Lookup books

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

```ruby
client.book("id")
client.book_by_isbn("ISBN")
client.book_by_title("Book title")
```

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

```ruby
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:

```ruby
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:

```ruby
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:

```ruby
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:

```ruby
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:

```ruby
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:

```ruby
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:

```ruby
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](http://www.goodreads.com/api#group.list).

### OAuth

For API calls requiring permission, such as write operations or browsing friends,
see our [OAuth tutorial](examples/oauth.md).

## 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](http://www.goodreads.com/api)

## License

The MIT License (MIT)

Copyright (c) 2011-2018 Dan Sosedoff, <dan.sosedoff@gmail.com>