{ "openapi": "3.0.1", "info": { "title": "Goodreads Books Scraper", "description": "Scrapes books from Goodreads Listopia lists: title, author, average rating, ratings count, cover and list rank/score per book, with an optional detail pass adding page count, format, language, awards, description and genres.", "version": "0.1", "x-build-id": "BWVeaUSbhtK4kUqWK" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/scrapyx~goodreads-books-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-scrapyx-goodreads-books-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/scrapyx~goodreads-books-scraper/runs": { "post": { "operationId": "runs-sync-scrapyx-goodreads-books-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/scrapyx~goodreads-books-scraper/run-sync": { "post": { "operationId": "run-sync-scrapyx-goodreads-books-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "listUrls" ], "properties": { "listUrls": { "title": "Goodreads Listopia list URLs", "type": "array", "description": "One or more Goodreads Listopia list URLs, e.g. https://www.goodreads.com/list/show/1.Best_Books_Ever. Open any list on Goodreads and paste its URL. Each list gets its own LIST_SUMMARY row. Only the /list/show/ form is accepted: Goodreads' robots.txt disallows its /search and /work surfaces for generic crawlers, so this actor refuses those URLs rather than fetching them.", "default": [], "items": { "type": "string" } }, "includeBookDetails": { "title": "Fetch book detail pages", "type": "boolean", "description": "Also fetch each book's page, adding its JSON-LD (average rating and rating count, page count, format, language, awards, full author list) plus description and genres from the page's Apollo cache. List rows already carry title, author, average rating, ratings count, cover and list rank/score. Off by default: one extra request per book.", "default": false }, "maxItems": { "title": "Max books per list", "minimum": 0, "type": "integer", "description": "Stop after this many books per list. Set to 0 for unlimited (still bounded by Max pages). Lists can be very large -- 'Best Books Ever' holds roughly 79,000 books at 100 per page.", "default": 100 }, "maxPages": { "title": "Max pages per list", "minimum": 1, "type": "integer", "description": "Hard cap on pagination depth (100 books/page) as a cost guard. It is not the correctness stop condition: past a list's real end Goodreads re-serves the last page forever rather than returning an empty one, so this actor stops on its own once a page yields no new book ids and reports that as paginationClampHit.", "default": 10 }, "maxConcurrency": { "title": "Max concurrent requests", "minimum": 1, "maximum": 10, "type": "integer", "description": "Upper bound on requests in flight at once, across list pages and detail fetches. Kept moderate by default: list pages are large (~770 KB each).", "default": 3 }, "minRequestInterval": { "title": "Minimum seconds between request starts", "minimum": 0, "type": "integer", "description": "Paces request starts without holding a concurrency slot. Raise it if you see repeated timeout or retry warnings in the log.", "default": 1 }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "No WAF or bot challenge was observed for Goodreads (8 TLS profiles, clean cold). Residential proxy is the default as this portfolio's standard baseline, deliberately without a country pin since the site is global.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } }