goodreads

README

goodreads

     

An unofficial Goodreads API client written in Go.

Usage

The first thing you'll need to do is register for a Goodreads API Key: https://www.goodreads.com/api/keys

Once you have your key, you can initialize a Goodreads client like so:

package main

import (
    "os"
    "github.com/KyleBanks/goodreads"
)

func main() {
    key := os.Getenv("API_KEY")	
    c := goodreads.NewClient(key)
}

With a client initialized, simply call the API methods as needed:

u, err := c.UserShow("38763538")
if err != nil {
    panic(err)
}
fmt.Printf("Loaded user details of %s:\n", u.Name)

The client function names match those of the Goodreads API documentation. For example, user.show is UserShow above. To see the full list of supported methods:

$ go doc github.com/KyleBanks/goodreads Client 

Examples

Example code is available in the example/ directory.

After you've obtained a Goodreads API Key, you can run the examples like so:

$ API_KEY="api key" go run example/example.go

Documentation

Overview

Package goodreads provides a REST client for the public goodreads.com API.

https://www.goodreads.com/api

Index

• type APIClient
• type Client
  • func NewClient(key string) *Client
  • func (c *Client) AuthorBooks(authorID string, page int) (*responses.Author, error)
  • func (c *Client) AuthorShow(authorID string) (*responses.Author, error)
  • func (c *Client) BookReviewCounts(isbns []string) ([]responses.ReviewCounts, error)
  • func (c *Client) ReviewList(userID, shelf, sort, search, order string, page, perPage int) ([]responses.Review, error)
  • func (c *Client) SearchBooks(query string, page int, field SearchField) ([]work.Work, error)
  • func (c *Client) ShelvesList(userID string) ([]responses.UserShelf, error)
  • func (c *Client) UserShow(id string) (*responses.User, error)
• type SearchField

Types

type APIClient

type APIClient interface {
	Get(string, func([]byte, interface{}) error, url.Values, interface{}) error
}

APIClient defines a client that can perform an action against a Goodreads API function, with parameters, and decode the response to a local struct.

type Client

type Client struct {
	APIKey string
	// contains filtered or unexported fields
}

Client wraps the public Goodreads API.

func NewClient

func NewClient(key string) *Client

NewClient initializes a Client with default parameters.

func (*Client) AuthorBooks

func (c *Client) AuthorBooks(authorID string, page int) (*responses.Author, error)

AuthorBooks returns a list of books by a particular author. https://www.goodreads.com/api/index#author.books

func (*Client) AuthorShow

func (c *Client) AuthorShow(authorID string) (*responses.Author, error)

AuthorShow returns the full details of an author. https://www.goodreads.com/api/index#author.show

func (*Client) BookReviewCounts

func (c *Client) BookReviewCounts(isbns []string) ([]responses.ReviewCounts, error)

BookReviewCounts returns the review statistics for a given list of ISBNs. https://www.goodreads.com/api/index#book.review_counts

func (*Client) ReviewList

func (c *Client) ReviewList(userID, shelf, sort, search, order string, page, perPage int) ([]responses.Review, error)

ReviewList returns the books on a members shelf. https://www.goodreads.com/api/index#reviews.list

func (*Client) SearchBooks

func (c *Client) SearchBooks(query string, page int, field SearchField) ([]work.Work, error)

SearchBooks returns a list of books based on a query string by title, author, or ISBN. https://www.goodreads.com/api/index#search.books

func (*Client) ShelvesList

func (c *Client) ShelvesList(userID string) ([]responses.UserShelf, error)

ShelvesList returns the list of shelves belonging to a user. https://www.goodreads.com/api/index#shelves.list

func (*Client) UserShow

func (c *Client) UserShow(id string) (*responses.User, error)

UserShow returns the public information about a given Goodreads user. https://www.goodreads.com/api/index#user.show

type SearchField

type SearchField string

SearchField defines the field types within which you can search. Defaults to AllFields.

const (
	// AuthorField lets you specify that you want to search author names only.
	AuthorField SearchField = "author"

	// TitleField lets you specify that you want to only search through book titles.
	TitleField SearchField = "title"

	// AllFields (the default) lets you search over everything.
	AllFields SearchField = "all"
)