Goodreads.js

A TypeScript Goodreads book parser for Node.js that extracts book data and bookshelf information from Goodreads.

Installation

npm install @kyraezikeuzor/goodreads.js

Usage

First, import the library:

import Goodreads from "@kyraezikeuzor/goodreads.js";

Get Book Information

Fetch detailed information about a book using its ISBN. Usage: Goodreads.getBook(isbn13).

try {
  const data = await Goodreads.getBook("9781501128035");
  console.log("Book Data:", data);
} catch (error) {
  console.log("Error:", error);
}

Response Format

{
  url: 'https://www.goodreads.com/search?q=9781501128035',
  title: 'The Unhoneymooners',
  author: 'Christina Lauren',
  pubDate: 'May 14, 2019',
  description: 'Olive is always unlucky: in her career, in love, in…well, everything...',
  cover: 'https://images-na.ssl-images-amazon.com/images/S/compressed.photo.goodreads.com/books/1548201335i/42201431.jpg',
  isbn13: '9781501128035',
  pages: 432,
  rating: 3.9,
  ratingCount: 1068296,
  reviewsCount: 97111,
  language: 'English',
  genres: [
    'Contemporary',
    'Enemies To Lovers',
    'Fiction',
    'Contemporary Romance',
    'Audiobook',
    'Romance',
    'Chick Lit'
  ]
}

Get Bookshelf

Retrieve books from a user's specific bookshelf.

try {
  const data = await Goodreads.getBookshelf("130048134", "read");
  console.log("Bookshelf Data:", data);
} catch (error) {
  console.log("Error:", error);
}

Parameters

• userId (string): The Goodreads user ID
• shelfName (string): The name of the shelf (e.g., "read", "to-read", "currently-reading")

Response Format

Returns an array of book objects with the same structure as getBook(), plus a readAt field indicating when the book was added to the shelf. Some array items may be null if the book data couldn't be parsed.

[
  {
    url: 'https://www.goodreads.com/search?q=9780448494517',
    title: 'A Reaper at the Gates',
    author: 'Sabaa Tahir',
    pubDate: 'June 12, 2018',
    // ... other book properties
    readAt: ''
  },
  null, // Some entries may be null if parsing failed
  {
    // ... another book object
    readAt: 'Jun 2025'
  }
  // ... more books
]

Book Data Fields

| Field | Type | Description | |-------|------|-------------| | url | string \| null | Goodreads search URL | | title | string \| null | Book title | | author | string \| null | Author name | | pubDate | string \| null | Publication date | | description | string \| null | Book description | | cover | string \| null | Cover image URL | | isbn13 | string \| null | ISBN-13 identifier | | pages | number \| null | Number of pages | | rating | number \| null | Average rating | | ratingCount | number \| null | Total number of ratings | | reviewsCount | number \| null | Total number of reviews | | language | string \| null | Book language | | genres | string[] \| null | Array of genre tags | | readAt | string \| null | Date added to shelf (bookshelf only) |

TypeScript Support

This package includes full TypeScript definitions. The main types exported are:

• Book: Individual book data structure
• Bookshelf: Array of books from a user's shelf

Error Handling

Always wrap API calls in try-catch blocks as the methods can throw errors for:

• Invalid ISBNs
• Network issues
• Parsing failures
• Invalid user IDs or shelf names

License

MIT

Contributing

Issues and pull requests are welcome on GitHub.