{ "openapi": "3.0.1", "info": { "title": "Goodreads Books & Reviews Scraper", "description": "Extract public Goodreads book metadata, ratings, and reader reviews from book URLs or search queries for research and book marketing workflows.", "version": "0.1", "x-build-id": "FLj6IE8ydJAcMSKge" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/fetch_cat~goodreads-books-reviews-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-fetch_cat-goodreads-books-reviews-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/fetch_cat~goodreads-books-reviews-scraper/runs": { "post": { "operationId": "runs-sync-fetch_cat-goodreads-books-reviews-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/fetch_cat~goodreads-books-reviews-scraper/run-sync": { "post": { "operationId": "run-sync-fetch_cat-goodreads-books-reviews-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", "properties": { "bookUrls": { "title": "Goodreads book URLs", "type": "array", "description": "Add up to 25 public HTTPS Goodreads /book/show/ URLs. Required only when no search queries are supplied. URLs and queries are combined, with duplicate book IDs processed once. The example is a form prefill, not an API default.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "queries": { "title": "Search queries", "type": "array", "description": "Add up to 10 nonempty queries, each at most 200 characters. Required only when no book URLs are supplied. Each query resolves up to five public book candidates, which may be different editions; this is not a full genre or list export. The example is a form prefill, not an API default.", "items": { "type": "string" } }, "includeReviews": { "title": "Include reviews", "type": "boolean", "description": "Defaults to true. Save visible reader review cards in addition to book metadata. Set false for metadata-only results. Each saved book and review is a separate paid item; not all reviews counted by Goodreads are visible.", "default": true }, "includeResearch": { "title": "Include edition and work research", "type": "boolean", "description": "Default false. Adds a nested research object to book rows: edition/work identity, publication, series, work-level rating and text-review language counts, and CSL JSON references. Uses source-bound public facts with no extra item fees. When includeReviews is explicitly false, qualified first-party metadata can supply all research after one anonymous bootstrap per run; otherwise the established page route is used within the same limits. Missing or incomplete source data is explained. Use JSON export to retain nested research; existing overview columns stay unchanged.", "default": false }, "maxReviewsPerBook": { "title": "Maximum reviews per book", "minimum": 0, "maximum": 100, "type": "integer", "description": "Integer from 0 to 100; default 10. Caps visible review rows per book, not the aggregate review count. Zero disables review rows. Reviews follow the fetched page order; no sorting or additional review pages are supported.", "default": 10 }, "maxRunSeconds": { "title": "Maximum run time (seconds)", "minimum": 35, "maximum": 270, "type": "integer", "description": "Optional safety budget from 35 to 270 seconds. All runs have an enforced 60-second processing ceiling; higher values are capped at 60 seconds. Saved rows remain available when a limit is reached." }, "proxyConfiguration": { "title": "Legacy connection settings", "type": "object", "description": "Direct connections only. Omit this field, use {}, or use only {\"useApifyProxy\":false}. Managed and custom proxies are unsupported. Unsupported settings that pass platform validation finish without extraction and display a warning.", "properties": { "useApifyProxy": { "type": "boolean", "title": "Use Apify Proxy", "description": "Must be false. This Actor supports direct connections only." } }, "additionalProperties": false } } }, "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 }, "PROXY_UNBLOCKER_UNITS": { "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 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } } } } } } } } }