{ "openapi": "3.0.1", "info": { "title": "Goodreads Review Scraper: Rating Distribution & Book Analytics", "description": "Goodreads Review Scraper: Extract book reviews, ratings, reviewer details, review dates, and book metadata. Analyze rating distributions, reader sentiment, review trends, and book performance to support publishing research, content analysis, and market intelligence.", "version": "1.0", "x-build-id": "rjyCD3GkOK6rE4qKZ" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/api-empire~goodreads-review-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-api-empire-goodreads-review-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/api-empire~goodreads-review-scraper/runs": { "post": { "operationId": "runs-sync-api-empire-goodreads-review-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/api-empire~goodreads-review-scraper/run-sync": { "post": { "operationId": "run-sync-api-empire-goodreads-review-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": [ "urls" ], "properties": { "urls": { "title": "๐Ÿ“š Book URLs", "type": "array", "description": "Paste one or more Goodreads book links. Tip: you can paste just the number from the URL (e.g. `26032825`) โ€” the link is completed for you. Example: 2 books ร— 20 reviews = up to 2 analytics rows + 40 review rows.", "items": { "type": "string" } }, "maxItems": { "title": "๐Ÿ”ข Max reviews per book", "minimum": 1, "maximum": 10000, "type": "integer", "description": "How many reviews to collect for each book (the book-analytics row is always emitted in addition). Example: 50 here ร— 3 books = up to 3 analytics rows + 150 review rows. Default is 20.", "default": 20 }, "includeRatingDistribution": { "title": "๐Ÿ“Š Include rating distribution & polarization", "type": "boolean", "description": "Add the 1โ˜…โ€“5โ˜… rating histogram (counts + percentages), positive/neutral/negative share, weighted average, standard deviation, and a 0โ€“1 polarization/controversy score to each book row. Default is true.", "default": true }, "includeBookDetails": { "title": "๐Ÿ“– Include book metadata", "type": "boolean", "description": "Add genres, page count, ISBN/ISBN13/ASIN, format, language, publisher, publication date, series, and author details to each book row. Default is true.", "default": true }, "filtersAndOptions": { "title": "โš™๏ธ Filters & sorting", "type": "object", "description": "Optional: change review sort order, language, and which edition reviews come from. Leave defaults for a quick start.", "properties": { "sortBy": { "title": "๐Ÿ“Š Sort reviews by", "type": "string", "description": "Popular โ€” most helpful first ยท Newest โ€” newest first ยท Oldest โ€” oldest first.", "editor": "select", "enum": [ "popular", "newest", "oldest" ], "default": "popular" }, "languageCode": { "title": "๐ŸŒ Review language", "type": "string", "description": "All languages โ€” no filter ยท Or choose one language to filter reviews.", "editor": "select", "enum": [ "all", "en", "bn", "fr", "de", "es", "it", "pt", "ru", "ja", "ko", "zh", "ar", "hi", "nl", "pl", "tr", "vi", "id", "th" ], "enumTitles": [ "All languages", "English", "Bengali", "French", "German", "Spanish", "Italian", "Portuguese", "Russian", "Japanese", "Korean", "Chinese", "Arabic", "Hindi", "Dutch", "Polish", "Turkish", "Vietnamese", "Indonesian", "Thai" ], "default": "all" }, "reviewEdition": { "title": "๐Ÿ“– Edition scope", "type": "string", "description": "All editions โ€” reviews for the whole work ยท This book only โ€” reviews for this edition.", "editor": "select", "enum": [ "ALL", "only_this_book" ], "default": "ALL" } } }, "proxyConfiguration": { "title": "๐Ÿ”’ Proxy (optional)", "type": "object", "description": "Optional. Turn on Apify Proxy for extra reliability. If a run is blocked, routing is escalated automatically (direct โ†’ datacenter โ†’ 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 } } } } } } } } } }