Created: 2011-07-16 15:35
Updated: 2019-01-03 06:23

Goodreads - Use NodeJS to tap into the Goodreads API

This is a dead simple wrapper for the Goodreads API when using NodeJS. I've only exposed a few GR API functions so far but would be happy to entertain adding more if there's demand.


  1. Install npm: curl | sh
  2. Grab this module from npm: npm install goodreads
  3. Include it in your program:
  • Coffeescript: goodreads = require 'goodreads'
  • Javascript: goodreads = require('goodreads');
  1. create a new instance of the Goodreads client:
  • Coffeescript: gr = new goodreads.client { 'key': key, 'secret': secret }
  • Javascript: gr = new goodreads.client({ 'key': key, 'secret': secret });
  1. Go get a goodreads developer key/secret from
  2. (optional) Add your key/secret to your environment variables so Nodejs can access them
  • Key: export GOODREADS_KEY=yourkey
  • Secret: export GOODREADS_SECRET=yoursecret
  1. Try it out! Maybe do a node examples/booklist.js to get an idea how things work


showUser - get user info with userName

  • input - valid userName
  • output - json (as callback)
  • Example: getShelves 'your_username', (json) ->
  • You must have created a username. You can do so here.

getShelves - Get all shelves for a given user

  • Input: userId
  • Output: json (as callback)
  • Example: getShelves '4085451', (json) ->

getSingleShelf - Get a specific list by ID

  • Input: shelfOptions object with userID (required), shelf (required), page (optional), and per_page (optional) properties.
  • Output: json (as callback)
  • Example: getSingleShelf {'userID': '4085451', 'shelf': 'web', 'page': 1, 'per_page': 200}, (json) ->

requestToken - OAUTH: calls back an object with oauthToken, oauthTokenSecret, and the URL!

  • Input: none
  • Output: json { oauthToken: 'iu1iojij14141411414', oauthTokenSecret: 'j1kljklsajdklf132141', url: ''}
  • Example: requestToken (callback) ->

processCallback - expects: oauthToken, oauthTokenSecret, authorize (from the query string) Note: call this after requestToken!

  • Input: oauthToken, oauthTokenSecret, authorize
  • Output: json { 'username': 'Brad Dickason', 'userid': '404168', 'success': 1, 'accessToken': '04ajdfkja', 'accessTokenSecret': 'i14k31j41jkm' }
  • Example: processCallback oauthToken, oauthTokenSecret, params.query.authorize, (callback) ->

getAuthor - Get paginated list of books for a given author

  • Input: authorId, page
  • Output: json (as callback)
  • Example: Example: getAuthor '18541', 2, (json) ->

getSeries - Get all books in a given series

  • Input: seriesId
  • Output: json (as callback)
  • Example: getSeries '40650', (json) ->

More to come!

Help, I need an adult!

First step: Check out the /examples folder. It's decently documented.

If you're still having issues, you can submit them here:


v0.0.5 - Removed OAuth workarounds

  • {showUser} method added - can get user information given their username.

v0.0.2 - Removed OAuth workarounds

  • OAuth Callback (processCallback) now properly returns an Access Token (accessToken) and Access Token Secret (accessTokenSecret)

v0.0.1 - First release! Woohoo!!

  • Added support getting a list of a user's shelves (getShelves)
  • Added support for getting all books on a single shelf (getSingleShelf)
  • Added support for an OAuth round trip via requestToken and processCallback
  • Started this ugly manual
Cookies help us deliver our services. By using our services, you agree to our use of cookies Learn more