Skip to navigation

list-scraper

View as Markdown

List Scraper

Scrapes books from a Goodreads community-curated reading list using a direct list URL. Returns the list title, description, and all books included in the list along with their rankings.


Request

Method: POST
URL: {{Instance Domain}}/api/list-scraper

Headers

KeyValueDescription
Content-Typeapplication/jsonIndicates the request body is JSON

Body

FieldTypeRequiredDescription
queryURLstringYesThe full Goodreads list page URL to scrape (e.g. https://www.goodreads.com/list/show/18834.BBC_Top_200_Books)

Example Body:

{
"queryURL": "https://www.goodreads.com/list/show/18834.BBC_Top_200_Books"
}

Response

200 Success

Returns a JSON object containing the list metadata and all books with their rankings.

{
"status": "Received",
"statusCode": 200,
...
}

Response Field Descriptions

FieldTypeDescription
statusstringHuman-readable status message
statusCodenumberHTTP status code of the response
listTitlestringTitle of the Goodreads reading list
listDescriptionstringDescription or summary of the reading list
booksarrayAll books in the list, each with ranking and metadata

Request

This endpoint expects an object.
queryURLstringRequiredformat: "uri"

Response

OK
statusstring
sourcestringformat: "uri"
scrapeURLstringformat: "uri"
titlestring
descstring
bookslist of objects
lastScrapeddatetime