Kyle Banks

Accessing the Goodreads API with Go

Written by @kylewbanks on Jan 27, 2019.

Goodreads is one of my favorite services, as I love reading (and spend quite a bit of time doing it, to be honest). My goal for 2019 is to read 75 books, and an additional 3 books in German as I’ve been learning the language over the last couple of years. Here’s where I’m at so far, and we’re only in January:

  1. [4 stars] The Man in the High Castle
  2. [4 stars] The Start-Up J Curve: The Six Steps to Entrepreneurial Success
  3. [1 stars] The General Theory of Employment, Interest, and Money
  4. [4 stars] Red Notice: A True Story of High Finance, Murder, and One Man’s Fight for Justice
  5. [3 stars] Natural Language Processing in Action
  6. [4 stars] An Astronaut’s Guide to Life on Earth
  7. [4 stars] Excelsior!: The Amazing Life of Stan Lee
  8. [4 stars] The End of the Fucking World
  9. [4 stars] 30-Second Economics
  10. [3 stars] The Grand Design
  11. [5 stars] Travelers in the Third Reich: The Rise of Fascism: 1919–1945

I tend to read a lot of books on finance, physics, history and software development, with some fiction and comics mixed in from time to time. Of the books above, I’d most recommend Travelers in the Third Reich: The Rise of Fascism: 1919–1945 and An Astronaut’s Guide to Life on Earth. The former is an eye-opening look at what it was like to live and travel in Germany between the two world wars, and really gives you perspective on how the second world war came to be. The latter is an inspiring autobiography of Chris Hadfield, a Canadian astronaut who dreamed of becoming an astronaut long before it was even possible for Canadians.

Anyways, I thought it would be cool to add a sort-of “bookshelf” to my website, and noticed that there weren’t any solid clients for the Goodreads API written in Go, so I decided to put one together at It’s pretty straightforward, but first you’ll need to sign up for a developer key at Once you’ve got that, you’re ready to go.

First, you’ll want to initialize a goodreads.Client using your developer key. Here’s how you might do that, using an API_KEY environment variable:

package main

import (


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

After that, you can make calls to the API using the corresponding function. For instance, to call the API endpoint, you’d use the UserShow function:

u, err := c.UserShow("user-id")

To quickly put together the markdown for the list of books above, here’s what I did:

reviews, _ := c.ReviewList("38763538", "read", "date_read", "", "d", 1, 11)
for i, rev := range reviews {
	fmt.Printf(" %d. [%d stars] [%s](%s)\n", i+1, rev.Rating, rev.Book.Title, rev.Book.Link)

This loads the read bookshelf for my Goodreads user ID, sorted by date_read in descending order, limiting to the 11 books I’ve read this year. It’s pretty straightforward, but there’s a lot of work to do in order to fill in all the API endpoints that Goodreads provides. If you’re interested, I’d be very grateful to receive pull requests at and to hear what you’re using the client for!

Let me know if this post was helpful on Twitter @kylewbanks or down below, and follow me to keep up with future posts!