{ "openapi": "3.0.1", "info": { "title": "Goodreads Scraper - Books, Authors, Ratings, Reviews & Leads", "description": "Scrape Goodreads books, authors, ratings, reviews and author leads. Get titles, ISBN/ASIN, genres, full rating breakdown, awards, descriptions, reviews and author contacts. Search by keyword or paste book/author/list/genre URLs. Monitor new releases. No login.", "version": "0.1", "x-build-id": "8f85o2BWUSscr0szG" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/scrapesage~goodreads-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-scrapesage-goodreads-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/scrapesage~goodreads-scraper/runs": { "post": { "operationId": "runs-sync-scrapesage-goodreads-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/scrapesage~goodreads-scraper/run-sync": { "post": { "operationId": "run-sync-scrapesage-goodreads-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": { "searchQueries": { "title": "Search queries (book titles, authors, ISBNs)", "type": "array", "description": "Keywords to look up via Goodreads' book auto-complete (e.g. \"project hail mary\", \"stephen king\", \"9780593135204\"). Each query returns the top matching books, which are then scraped in full. For bulk discovery, prefer Listopia list, genre or author URLs in Start URLs.", "items": { "type": "string" } }, "startUrls": { "title": "Start URLs (books, authors, lists, genres, series)", "type": "array", "description": "Goodreads URLs to scrape. Supports book pages (/book/show/…), author pages (/author/show/…), Listopia lists (/list/show/…), genre/shelf pages (/genres/… or /shelf/show/…) and series pages (/series/…). List/genre/series/author pages are expanded into their books.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "bookIds": { "title": "Book IDs or ISBNs", "type": "array", "description": "Goodreads numeric book IDs (e.g. 2767052) or ISBN-10/ISBN-13 (e.g. 9780439023481). Each is fetched as a full book record.", "items": { "type": "string" } }, "maxBooks": { "title": "Max books", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Maximum number of book records to scrape across all queries and URLs. Reviews and author leads are additional and not counted against this limit.", "default": 50 }, "includeReviews": { "title": "Include reviews", "type": "boolean", "description": "Also output the community reviews embedded on each book page (rating, full text, date, likes, comments, shelf, reviewer). Up to ~30 per book.", "default": false }, "maxReviewsPerBook": { "title": "Max reviews per book", "minimum": 1, "maximum": 30, "type": "integer", "description": "How many reviews to output per book when Include reviews is on (the book page carries up to ~30).", "default": 20 }, "outputAuthorLeads": { "title": "Output author leads", "type": "boolean", "description": "Also output one deduplicated lead record per author found across the scraped books — name, Goodreads profile, follower count, ratings, books, bio, personal website, genres and a 0-100 lead score. Ideal for book-marketing / publishing outreach.", "default": false }, "enrichAuthorWebsites": { "title": "Enrich author websites (emails, phones, socials)", "type": "boolean", "description": "For author leads that list a personal website, crawl it (home + /contact + /about, max 3 pages) for contact emails, phone numbers and social links. Goodreads never exposes emails — this is the only way to get them.", "default": false }, "includeAuthorBooks": { "title": "Scrape an author's books from author URLs", "type": "boolean", "description": "When an author page is given as a Start URL, also scrape the books listed on that page (up to Max books).", "default": true }, "monitorMode": { "title": "Monitor mode — only new records", "type": "boolean", "description": "Remember IDs seen in previous runs (in a named key-value store) and emit only books/reviews/authors that are new since the last run. Works alongside Apify Schedules for hands-off monitoring.", "default": false }, "monitorKey": { "title": "Monitor key", "type": "string", "description": "Names the monitor store so different searches keep separate memory (e.g. \"fantasy-new-releases\"). Reuse the same key across scheduled runs to keep deduplicating against the same history.", "default": "default" }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Proxy settings. Goodreads is reachable on Apify datacenter proxies (the default); switch to Residential if you hit rate challenges at high volume.", "default": { "useApifyProxy": true } }, "urlsFromFile": { "title": "Import URLs from a file", "type": "string", "description": "Paste a list of URLs (one per line), OR one link to a .txt/.csv file, Google Sheet or Google Drive file containing them. Lets you import many Start URLs at once instead of typing each. Google Sheet/Drive share links are handled automatically." } } }, "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 } } } } } } } } } }