{ "openapi": "3.0.1", "info": { "title": "Goodreads Book Scraper With Ratings Analytics", "description": "Goodreads Book Scraper extracts book details, ratings, review counts, author data, genres, publication info, descriptions, and URLs. Analyze rating trends and reader feedback for book research, market analysis, competitor insights, and publishing intelligence.", "version": "0.1", "x-build-id": "ogzK02EHsBPNkOlQo" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/scrapier~goodreads-book-search/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-scrapier-goodreads-book-search", "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/scrapier~goodreads-book-search/runs": { "post": { "operationId": "runs-sync-scrapier-goodreads-book-search", "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/scrapier~goodreads-book-search/run-sync": { "post": { "operationId": "run-sync-scrapier-goodreads-book-search", "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": { "bookQueries": { "title": "📚 Book searches to analyze", "type": "array", "description": "One search phrase (for example *historical fiction* or *stephen king*) or one full Goodreads search URL per line. Every line is analyzed separately and its books are tagged with the query that produced them.", "items": { "type": "string" } }, "booksPerQuery": { "title": "🔢 Books to keep per search", "minimum": 1, "maximum": 10000, "type": "integer", "description": "How many books that PASS your filters should be kept for each search line. Paging continues until this many books match or the search runs out of results. Example: 25 with a 4.0 minimum rating keeps paging until 25 books rated 4.0+ are found. Default is 10." }, "percentileScope": { "title": "📊 Popularity percentile is measured against", "enum": [ "run", "query" ], "type": "string", "description": "Sets the comparison pool for `popularityPercentile`. It is a RUNNING percentile: each row is ranked by its ratings volume against the books already analyzed in the chosen pool at the moment that row is saved, and `popularityPercentileBasis` reports how many books that pool held. Default compares against the whole run." }, "ratingsBreakdownStyle": { "title": "🧮 Star breakdown columns", "enum": [ "counts_and_percent", "counts_only", "percent_only" ], "type": "string", "description": "Choose which star columns are written. `counts_only` keeps `ratings1Star` ... `ratings5Star`, `percent_only` keeps `ratings1StarPercent` ... `ratings5StarPercent`, and the default writes both. Percentages are each star's share of that book's total ratings, rounded to 2 decimals." }, "minAverageRating": { "title": "⭐ Minimum average rating", "minimum": 0, "maximum": 5, "type": "number", "description": "Keep only books whose average rating is at least this value (0 - 5). Example: 4.2 drops everything rated below 4.2. Leave empty to keep every rating." }, "minRatingsTotal": { "title": "👥 Minimum number of ratings", "minimum": 0, "type": "integer", "description": "Keep only books with at least this many ratings in total. Useful for skipping obscure titles whose average is based on a handful of votes. Example: 5000. Leave empty to keep every book." }, "publishedFromYear": { "title": "📅 Published from year", "minimum": 0, "maximum": 2100, "type": "integer", "description": "Keep only editions published in this year or later, read from the book's own publication date. Example: 2015. Leave empty for no lower bound." }, "publishedToYear": { "title": "📆 Published up to year", "minimum": 0, "maximum": 2100, "type": "integer", "description": "Keep only editions published in this year or earlier. Example: 2023. Leave empty for no upper bound." }, "genresInclude": { "title": "✅ Keep only these genres", "type": "array", "description": "One genre or shelf name per line. A book is kept when at least one of its own genres matches any line (case-insensitive, whole-word match inside the genre name, so *Fiction* matches *Historical Fiction* but not *Nonfiction*). Example: Fantasy. Leave empty to accept every genre.", "items": { "type": "string" } }, "genresExclude": { "title": "🚫 Drop these genres", "type": "array", "description": "One genre or shelf name per line. A book is dropped as soon as any of its own genres matches a line (case-insensitive, whole-word match inside the genre name). Example: Romance. Applied after the keep-list.", "items": { "type": "string" } }, "urls": { "title": "🔗 urls (legacy key for the searches)", "type": "array", "description": "Accepted so an input written for the original Goodreads Book Scraper still runs unchanged. Used only when *Book searches to analyze* above is empty.", "items": { "type": "string" } }, "resultsPerQuery": { "title": "📊 resultsPerQuery (legacy key for the per-search limit)", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Accepted so an existing input JSON still runs. Used only when *Books to keep per search* above is empty." }, "delayMs": { "title": "⏱️ Pause between result pages (ms)", "minimum": 0, "maximum": 60000, "type": "integer", "description": "Milliseconds to wait between two pages of the same search. The original actor read this value without showing it in the form - it is now a real, documented field. Default is 1000." }, "proxyConfiguration": { "title": "🌍 Network settings (optional)", "type": "object", "description": "Optional. Leave off and the run goes out on the platform's own connection; turn it on to route requests through Apify Proxy with the groups and country you choose." } } }, "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 } } } } } } } } } }