{ "openapi": "3.0.1", "info": { "title": "Goodreads Scraper — Books, Reviews, Authors, Lists", "description": "Scrape Goodreads books, reviews, authors, lists, series, and search results from any URL or text query. MCP-ready, all-in-one, residential proxy default, $0.005 per result.", "version": "1.1", "x-build-id": "3eJBOwSaj9DbeGPOt" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/khadinakbar~goodreads-all-in-one-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-khadinakbar-goodreads-all-in-one-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/khadinakbar~goodreads-all-in-one-scraper/runs": { "post": { "operationId": "runs-sync-khadinakbar-goodreads-all-in-one-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/khadinakbar~goodreads-all-in-one-scraper/run-sync": { "post": { "operationId": "run-sync-khadinakbar-goodreads-all-in-one-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": [ "targets" ], "properties": { "targets": { "title": "Goodreads URLs or text queries", "type": "array", "description": "List of Goodreads URLs OR plain-text search queries. Each item can be a book URL (https://www.goodreads.com/book/show/40097951), author URL (/author/show/...), list URL (/list/show/...), series URL (/series/...), or a text query like 'sapiens yuval noah harari'. Auto-detected per item. NOT for private user shelves requiring login.", "items": { "type": "string" } }, "resultsPerTarget": { "title": "Max results per target", "minimum": 1, "maximum": 500, "type": "integer", "description": "Cap on records returned per target. For books, this caps reviews collected (book metadata always returned). For lists and search, this caps entries. Defaults to 50. Maximum 500 per target to keep runs predictable. Not the total across all targets — applied per-target.", "default": 50 }, "scrapeReviews": { "title": "Scrape reviews for book targets", "type": "boolean", "description": "When true, opens each book URL and also pulls its reviews up to resultsPerTarget. When false, returns only the book metadata record (faster and cheaper). Has no effect on non-book targets. Defaults to true.", "default": true }, "reviewsLanguage": { "title": "Reviews language filter", "enum": [ "all", "en", "es", "fr", "de", "it", "pt", "nl", "ru", "ja", "zh", "ko" ], "type": "string", "description": "Limit reviews to a specific language. Use ISO 639-1 codes like 'en', 'es', 'fr', or 'all' for no filter. Defaults to 'all'. Filtering uses Goodreads' built-in language tag — reviews with no detected language pass through 'all' only.", "default": "all" }, "minRating": { "title": "Minimum review rating", "minimum": 1, "maximum": 5, "type": "integer", "description": "Skip reviews below this star rating (1-5). Set to 1 to return every review. Use 4 for positive-only sentiment, 2 for negative-only when combined with maxRating. Applies only to review records, not books.", "default": 1 }, "maxRating": { "title": "Maximum review rating", "minimum": 1, "maximum": 5, "type": "integer", "description": "Skip reviews above this star rating (1-5). Set to 5 for no upper bound. Combine with minRating to slice review sentiment (e.g., min=1 max=2 returns only 1-2 star reviews). Applies only to review records.", "default": 5 }, "responseFormat": { "title": "Response shape for AI agents", "enum": [ "concise", "detailed" ], "type": "string", "description": "Controls dataset item richness. 'concise' returns a token-efficient subset of fields (good for AI agents and recommendation systems). 'detailed' returns every parsed field including raw HTML descriptions and reviewer profile metadata. Defaults to 'detailed' for humans.", "default": "detailed" }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Apify proxy settings. Residential proxies are recommended for reliability — Goodreads occasionally tightens anti-bot. Datacenter works for low volume. Defaults to residential.", "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 } } } } } } } } } }