Goodreads hub

Goodreads Listopia List API

A Listopia list with its ranked books, scores and votes.

GET /v1/goodreads/lists/{listId}

1 credit Failed requests are free A not-found answer is still charged

About this endpoint

GET /v1/goodreads/lists/{listId} takes the number from the list URL, for example 1 for Best Books Ever. On found, data.list carries id, title, url, description, booksCount, voters, likes, tags and books, each with rank, score, votes, id, title, url, cover, authors, averageRating and ratingsCount. 100 books a page; follow page.nextPage while page.hasMore is true.

Price

From $1.35 per 1,000 requests

1 credit per request. Failed requests are free.

Scale pack
$1.64 / 1,000
Growth pack
$2.36 / 1,000

The lowest rate is on annual plans; packs are pay as you go.

Example request

Send your API key in the x-api-key header. New accounts get 100 free credits, no card needed.

Request
cURL

Example response

A 200 response. Live responses have the same shape with current data.

Request
JSON

Goodreads Listopia List API FAQ

How are books ranked?

By the list score the site computes from the number of voters and how highly they ranked each book. rank, score and votes are returned as the site shows them.

How deep can I page?

As deep as the list goes, 100 books a page. Long lists such as Best Books Ever run to hundreds of pages.

How many credits does a call cost?

Pricing is documented on the operation in the API registry (shown on this page). Confirm on every response with meta.creditsCharged: that field is the billing source of truth.

What does lookupStatus mean here?

found means data.list is the list. not_found means no list has this id.