{ "openapi": "3.0.1", "info": { "title": "Goodreads Book Scraper With Full Book Details", "description": "Searches Goodreads for books by title, author, or keyword, extracting book names, authors, ratings, reviews count, genres, descriptions, and URLs. Ideal for reading research, trend analysis, recommendation engines, and large-scale Goodreads book discovery", "version": "0.1", "x-build-id": "xKUeE6HFSOBdJqVML" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/scrapio~goodreads-book-search/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-scrapio-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/scrapio~goodreads-book-search/runs": { "post": { "operationId": "runs-sync-scrapio-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/scrapio~goodreads-book-search/run-sync": { "post": { "operationId": "run-sync-scrapio-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": { "bookSearchTerms": { "title": "๐Ÿ“š Book searches", "type": "array", "description": "One book search phrase per line (for example *python programming*), or a full Goodreads book-search URL. Every line is scraped separately and tagged in the output with the query that produced it.", "items": { "type": "string" } }, "booksPerSearch": { "title": "๐Ÿ”ข Books per search", "minimum": 1, "maximum": 10000, "type": "integer", "description": "How many books to collect for EACH line above. Result pages are walked until this count is reached or the search runs out of books. Similar-book rows do not count towards it. Default is 10." }, "maxBooksTotal": { "title": "๐Ÿ›‘ Total book cap (all searches)", "minimum": 0, "type": "integer", "description": "Hard ceiling on books across ALL search lines combined. Example: 3 searches x 10 books per search with a cap of 15 stops at 15 books. Set 0 for no ceiling. Default is 0.", "default": 0 }, "fetchFullBookDetails": { "title": "๐Ÿ“– Add full book details", "type": "boolean", "description": "ON adds ISBN / ISBN13 / ASIN, format, page count, language, publisher, publication date, genres, series and large cover to every book. OFF returns the plain search-listing fields only. Default is ON.", "default": true }, "includeBookDescription": { "title": "๐Ÿงพ Include the book description", "type": "boolean", "description": "Adds the full book blurb text to each row. Turn OFF for slimmer rows when you only need the structured fields. Needs full book details to be ON. Default is ON.", "default": true }, "includeAuthorProfile": { "title": "โœ๏ธ Include author profile", "type": "boolean", "description": "Adds the author's Goodreads page URL, biography, total published works and follower count to each book row. Needs full book details to be ON. Default is ON.", "default": true }, "includeSimilarBooks": { "title": "๐Ÿงญ Also collect similar books", "type": "boolean", "description": "ON adds a separate row per similar title, linked to its parent book, plus a similarBooksCount column on the book row. Default is OFF.", "default": false }, "maxSimilarBooksPerBook": { "title": "๐Ÿ”ข Similar books per book", "minimum": 1, "maximum": 20, "type": "integer", "description": "Caps how many similar titles are kept for each book. Example: 10 books x 5 similar = up to 50 extra rows. Only used when similar books are ON. Default is 5.", "default": 5 }, "urls": { "title": "๐Ÿ”— Search terms or Goodreads URLs (legacy key)", "type": "array", "description": "Same meaning as Book searches. Used only when Book searches is empty.", "items": { "type": "string" } }, "resultsPerQuery": { "title": "๐Ÿ“Š Books per query (legacy key)", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Same meaning as Books per search. Used only when Books per search is empty." }, "requestDelayMs": { "title": "โณ Pause between result pages (ms)", "minimum": 0, "maximum": 60000, "type": "integer", "description": "Milliseconds to wait between two result pages of the same search. Raise it for gentler pacing, lower it for speed. Default is 1000." }, "proxyConfiguration": { "title": "๐Ÿ›ก๏ธ Proxy (optional)", "type": "object", "description": "Leave off for the fastest start. Turn it on to route requests through Apify Proxy and pick groups or a country.", "properties": { "useApifyProxy": { "title": "โœ… Use Apify Proxy", "type": "boolean", "description": "Turn on to route requests through Apify Proxy from the first request." }, "apifyProxyGroups": { "title": "๐Ÿ“Œ Proxy groups", "type": "array", "items": { "type": "string" }, "description": "Optional proxy groups to use." }, "apifyProxyCountry": { "title": "๐ŸŒ Proxy country", "type": "string", "description": "Optional ISO-2 country code (e.g. US, GB). Leave blank for no country filter." } } } } }, "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 } } } } } } } } } }