Goodreads Lists API
The Listopia lists that carry a tag.
GET /v1/goodreads/lists1 credit Failed requests are free A not-found answer is still charged
About this endpoint
GET /v1/goodreads/lists?tag= returns the Listopia lists that carry a tag, for example fantasy, romance or best, 30 a page. Each list has id, title, url, booksCount, voters and the covers of its top books. Pass a list's id to the list route for its ranked books. An unused tag returns an empty list.
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.
Example response
A 200 response. Live responses have the same shape with current data.
Goodreads Lists API FAQ
How do I get the books on a list?
Pass the list id to GET /v1/goodreads/lists/{listId}; it returns the ranked books, 100 a page.
What tags can I use?
Any Listopia tag, in lowercase with hyphens for spaces, for example science-fiction.
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.
Does an unknown tag fail?
No. It returns an empty lists array with page.hasMore false.
Other Goodreads endpoints
- BookGET /v1/goodreads/books/{bookId}
- Book reviewsGET /v1/goodreads/books/{bookId}/reviews
- Book editionsGET /v1/goodreads/books/{bookId}/editions
- Review commentsGET /v1/goodreads/reviews/comments
- Book searchGET /v1/goodreads/search
- SeriesGET /v1/goodreads/series/{seriesId}
- AuthorGET /v1/goodreads/authors/{authorId}
- Author booksGET /v1/goodreads/authors/{authorId}/books