Goodreads

Get Goodreads list

Get a Goodreads Listopia list with its ranked books, scores and votes.

GET/v1/goodreads/lists/{listId}
x-api-keystringheader

API key (`sfk_...`)

Parameters
2
listIdintegerrequiredpath

Goodreads list id: the number in the page URL, e.g. `1`. A slug such as `1.Best_Books_Ever` or the full URL also works.

≥ 1 · ≤ 2147483647

pageintegeroptionalquery

Page number, starting at 1. Pass `page.nextPage` from the previous response to get the next page. Default 1, at most 1000.

≥ 1 · ≤ 1000

Response fields
39

Endpoint-specific response payload.

datalookupStatus
string

`not_found` when no list has this id.

one of: found, not_found

The list when found; otherwise null.

datalistid
integer

List id.

datalisttitle
string

List title.

datalisturl
string

List page URL.

datalistdescription
stringnullable

Description as plain text.

datalistbooksCount
integernullable

Books on the list.

datalistvoters
integernullable

People who voted.

datalistlikes
integernullable

Likes.

Tags on the list.

datalisttags[]
stringoptional

Books on this page in rank order, 100 a page.

datalistbooks[]id
integer

Book id (the number in `/book/show/{id}`).

datalistbooks[]workId
integernullable

Work id shared by every edition, when shown.

datalistbooks[]title
string

Title as the site shows it, with the series.

datalistbooks[]url
string

Book page URL.

datalistbooks[]cover
stringnullable

Cover image URL. Link only; not hosted by Social Fetch.

Authors named on the row.

datalistbooks[]authors[]id
integernullable

Author id.

datalistbooks[]authors[]name
string

Author name.

datalistbooks[]authors[]url
stringnullable

Author page URL.

datalistbooks[]averageRating
numbernullable

Average rating, 0 to 5.

datalistbooks[]ratingsCount
integernullable

Number of ratings.

datalistbooks[]publishedYear
integernullable

Year first published, when shown.

datalistbooks[]editionsCount
integernullable

Number of editions, when shown.

datalistbooks[]rank
integernullable

Place in the list.

datalistbooks[]score
integernullable

List score.

datalistbooks[]votes
integernullable

People who voted for it.

Pagination state for the current page.

datapagepage
integer

Current page number.

≥ 0

datapagehasMore
boolean

Whether another page is available.

datapagenextPage
integernullable

Next page number; null on the last page.

≥ 0

Metadata describing the request and billing outcome.

metarequestId
string

Unique request identifier for tracing this API call.

min 1 chars

metacreditsCharged
integer

Credits charged for this request.

≥ 0

metaversion
string

Public API version that served the response.

one of: v1

metastale
booleanoptional

Present, and `true`, only when the source couldn't be reached and this is the last good answer for the same request instead, up to 24 hours old. Absent on every live answer.

one of: true

metafetchedAt
stringoptional

When a stale answer (`stale: true`) was originally fetched (ISO 8601, UTC). Absent on every live answer.

Code example

curl "https://api.socialfetch.dev/v1/goodreads/lists/1" \
  -H "x-api-key: YOUR_API_KEY"

Responses

Goodreads Listopia list.