{
  "openapi": "3.0.1",
  "info": {
    "title": "Goodreads Scraper: Books, Ratings, ISBN, Genres and Reviews",
    "description": "Scrape Goodreads books by keyword, ISBN, list, shelf, genre, author, series or book link: rating, ratings count, reviews count, genres, pages, published date, ISBN, description and cover. Add review rows with text and stars. No login.",
    "version": "0.1",
    "x-build-id": "F5EiuZVHN34AxwCKk"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/themineworks~goodreads-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-themineworks-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/themineworks~goodreads-scraper/runs": {
      "post": {
        "operationId": "runs-sync-themineworks-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/themineworks~goodreads-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-themineworks-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": "Keywords or ISBNs",
            "type": "array",
            "description": "Words as you would type them in the Goodreads search box, one per line, for example dune, stephen king or atomic habits. An ISBN (10 or 13 digits) returns that exact book. Goodreads links work here too. Each keyword is one search, up to 2,000 books each.",
            "items": {
              "type": "string"
            }
          },
          "startUrls": {
            "title": "Goodreads links (optional)",
            "type": "array",
            "description": "Links copied from goodreads.com: a book (https://www.goodreads.com/book/show/41865.Twilight), a Listopia list (https://www.goodreads.com/list/show/1.Best_Books_Ever), a shelf (https://www.goodreads.com/shelf/show/art), a genre (https://www.goodreads.com/genres/most_read/fantasy), an author (https://www.goodreads.com/author/list/1221698.Neil_Gaiman), a series or a search link. Lists, authors and searches are read page by page.",
            "items": {
              "type": "string"
            }
          },
          "searchField": {
            "title": "Search in",
            "enum": [
              "all",
              "title",
              "author"
            ],
            "type": "string",
            "description": "Which part of the book the keywords must match, as on the Goodreads search page.",
            "default": "all"
          },
          "maxItems": {
            "title": "Max books per search or link",
            "minimum": 1,
            "maximum": 2000,
            "type": "integer",
            "description": "The most books to return for each keyword or link, 1 to 2,000. Goodreads serves up to 2,000 results for one search; a shelf, genre or series page holds up to 100.",
            "default": 20
          },
          "output": {
            "title": "What to return",
            "enum": [
              "books",
              "books_and_reviews",
              "reviews"
            ],
            "type": "string",
            "description": "Books only gives one row per book. Books and their reviews adds one row per review after each book. Reviews only gives just the review rows (each still names its book).",
            "default": "books"
          },
          "maxReviewsPerBook": {
            "title": "Max reviews per book",
            "minimum": 1,
            "maximum": 5000,
            "type": "integer",
            "description": "Used when reviews are on. Reviews come in the order the Goodreads book page shows them, 100 per call.",
            "default": 30
          },
          "reviewRatingMin": {
            "title": "Reviews: lowest stars (optional)",
            "minimum": 1,
            "maximum": 5,
            "type": "integer",
            "description": "Only reviews with at least this many stars, 1 to 5. Leave empty for all."
          },
          "reviewRatingMax": {
            "title": "Reviews: highest stars (optional)",
            "minimum": 1,
            "maximum": 5,
            "type": "integer",
            "description": "Only reviews with at most this many stars, 1 to 5. Set both to 1 for one star reviews only."
          },
          "reviewLanguage": {
            "title": "Reviews: language (optional)",
            "type": "string",
            "description": "A two letter language code, for example en, es or de, to get reviews written in that language only."
          },
          "proxyConfiguration": {
            "title": "Proxy (optional)",
            "type": "object",
            "description": "Leave empty: the actor goes direct and switches to an Apify datacenter IP on its own when needed. Set it only to force your own proxy."
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}