{
  "openapi": "3.0.1",
  "info": {
    "title": "Google Maps Reviews Scraper — Date Range, New-Only, Complete",
    "description": "Google Maps reviews by place id, URL, short link or name. One row per review: stars, text, owner replies, exact dates, translation, photos, reviewer. Free place row: rating, review count, completeness check. Free filters: date range, only new reviews, negative reviews, text-only, keywords, language.",
    "version": "1.4",
    "x-build-id": "rrkX1YSbuYmbLpGxu"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/kestrel~google-maps-reviews-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-kestrel-google-maps-reviews-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/kestrel~google-maps-reviews-scraper/runs": {
      "post": {
        "operationId": "runs-sync-kestrel-google-maps-reviews-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/kestrel~google-maps-reviews-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-kestrel-google-maps-reviews-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": {
          "places": {
            "title": "Places",
            "uniqueItems": true,
            "type": "array",
            "description": "One place per line, any mix: a Google Maps place URL, a maps.app.goo.gl or share.google short link, a place id (\"ChIJD3uTd9hx5kcR1IQvGfr8dbk\"), a CID, a feature id, a Maps search URL, or just \"Katz's Delicatessen, New York\". A place Google does not know ends as a free not_found status row, never a failed run. A chain name can resolve to another branch: for repeat runs pass the URL, place id or CID. The same place given twice is read once; a pasted spreadsheet column works as it is.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "maxReviewsPerPlace": {
            "title": "Max reviews per place",
            "minimum": 0,
            "maximum": 1000000,
            "type": "integer",
            "description": "Reviews delivered and charged per place, counted after filters: 100 (default), 0 = every review the place has. The main cost control: 100 reviews × 50 places is at most 5,000 reviews = $5.00. Use 0 with fromDate for \"every review since 1 July\", 0 alone for a full backup. Filters never count against it: 50 asked with onlyWithText = 50 reviews with text.",
            "default": 100
          },
          "fromDate": {
            "title": "From date",
            "type": "string",
            "description": "Only reviews published on or after this day: \"2026-07-01\" (YYYY-MM-DD) or a look-back such as \"30 days\", \"2 weeks\", \"6 months\". Empty (default) = no lower bound. With sort newest the actor stops reading at this date, so \"reviews from the last 30 days\" of a place with 50,000 reviews reads one page, not a thousand, and only reviews in range are billed. Use a look-back for scheduled runs: the input never needs editing.",
            "default": ""
          },
          "toDate": {
            "title": "To date",
            "type": "string",
            "description": "Only reviews published on or before this day: \"2026-09-30\" (YYYY-MM-DD) or a look-back such as \"7 days\". Empty (default) = no upper bound. With fromDate it is a true date range, e.g. one calendar quarter; reviews newer than toDate are read past free. Dates compare with published_at (first posted); set includeEdited true to also count a review edited inside the range.",
            "default": ""
          },
          "sort": {
            "title": "Order",
            "enum": [
              "newest",
              "most_relevant",
              "highest",
              "lowest"
            ],
            "type": "string",
            "description": "\"newest\" (default), \"most_relevant\" (Google's own order), \"highest\", \"lowest\". Keep newest for date ranges and monitoring: the walk stops at fromDate, so nothing older is read or paid for. \"lowest\" answers \"the complaints about this place\" fastest; combine it with maxStars 2. With onlyNew the order is always newest.",
            "default": "newest"
          },
          "onlyNew": {
            "title": "Only new reviews since the last run",
            "type": "boolean",
            "description": "false (default) keeps no memory. Set true on the FIRST run and every repeat to remember delivered reviews under monitorKey; a false run does not register its output. First run returns up to maxReviewsPerPlace. Later runs suppress remembered IDs and older backlog, using newest order. This is monitoring, not paging through history or importing an external ID list. Filtered/already-delivered reviews are free; no new rows costs $0. includeEdited controls repeat delivery of edits.",
            "default": false
          },
          "monitorKey": {
            "title": "Monitor key",
            "type": "string",
            "description": "Name this review feed, e.g. \"louvre-negative-daily\" (default \"default\"; 1-40 letters, digits or hyphens). Use the SAME key, place and filters on the first onlyNew=true run and every repeat. Separate feeds or changed filter sets need different keys so their memories do not hide reviews from one another. This names stored state; it is not a password or a list of IDs. Ignored when onlyNew=false."
          },
          "includeEdited": {
            "title": "Also deliver edited reviews",
            "type": "boolean",
            "description": "false (default) = a review is delivered once, as first seen. true = with onlyNew, a review whose author edited it after you received it is delivered (and billed) again with edited = true and both dates; with a date range, a review edited inside the range counts as inside it.",
            "default": false
          },
          "minStars": {
            "title": "Min stars",
            "minimum": 0,
            "maximum": 5,
            "type": "integer",
            "description": "Keep reviews with at least this many stars, 1 to 5, e.g. 4 for positive reviews only. 0 (default) = no lower bound. Free: filtered reviews are never charged.",
            "default": 0
          },
          "maxStars": {
            "title": "Max stars",
            "minimum": 0,
            "maximum": 5,
            "type": "integer",
            "description": "Keep reviews with at most this many stars, e.g. 2 for negative reviews and complaints only, 3 for \"everything below 4 stars\". 0 (default) = no upper bound. Free; pair it with sort \"lowest\" to reach them first.",
            "default": 0
          },
          "onlyWithText": {
            "title": "Only reviews with text",
            "type": "boolean",
            "description": "false (default) = star-only ratings are delivered too. true = skip them: about a third of Google reviews carry no text, and with this on they are read past free, so you pay only for reviews that say something — what sentiment analysis and AI summaries need. maxReviewsPerPlace then counts only reviews with text.",
            "default": false
          },
          "hasOwnerReply": {
            "title": "Owner reply",
            "enum": [
              "any",
              "yes",
              "no"
            ],
            "type": "string",
            "description": "\"any\" (default) keeps reviews with or without a reply and returns owner_reply_text / owner_reply_at when present. Leave \"any\" for \"include any owner reply\"; replies need no extra flag or fee. \"yes\" filters to replied-to reviews; \"no\" keeps only reviews awaiting a reply. Example: \"no\" for a reputation team's unanswered-review queue. Filtering happens before delivery and billing.",
            "default": "any"
          },
          "keywords": {
            "title": "Keywords (any of)",
            "type": "array",
            "description": "Keep a review only if its text contains at least one of these words or phrases, case-insensitive, e.g. [\"parking\", \"wait time\"]. Empty (default) = no keyword filter. Matched in the original text and, with translate \"both\", in Google's translation too. Free.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "excludeKeywords": {
            "title": "Exclude keywords",
            "type": "array",
            "description": "Drop a review if its text contains any of these words or phrases, e.g. [\"delivery\"]. Empty (default) = nothing dropped. Case-insensitive, matched like keywords. Free.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "reviewLanguages": {
            "title": "Review languages",
            "type": "array",
            "description": "Keep only reviews written in these languages, as two-letter codes: [\"en\"] or [\"de\", \"fr\"]. Empty (default) = every language. Uses the language Google detected (original_language); star-only ratings have no language and are dropped when this is set. Free.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "hasPhotos": {
            "title": "Only reviews with photos",
            "type": "boolean",
            "description": "false (default) = all reviews. true = only reviews that carry at least one photo (URLs in photos). Free.",
            "default": false
          },
          "translate": {
            "title": "Text",
            "enum": [
              "original",
              "translated",
              "both"
            ],
            "type": "string",
            "description": "\"original\" (default) = text as written, text_translated empty. \"translated\" = text holds Google's translation into language (reviews already in that language are unchanged). \"both\" = text original, text_translated the translation. Use \"translated\" or \"both\" for \"all reviews in English\" or sentiment analysis across languages. The owner reply follows the same choice. Free.",
            "default": "original"
          },
          "language": {
            "title": "Language",
            "type": "string",
            "description": "Interface language as a code: \"en\" (default), \"de\", \"fr\", \"es\", \"pt-BR\", \"ja\". Sets the language of translations (translate), of place categories and of Google's relative dates (published_text). Exact dates (published_at, updated_at) never depend on it.",
            "default": "en"
          },
          "country": {
            "title": "Country",
            "type": "string",
            "description": "Two-letter country Google is asked from (gl): \"us\" (default), \"gb\", \"de\", \"jp\". Rarely matters: change it only when a plain name resolves to a branch in the wrong country. It does not filter reviews.",
            "default": "us"
          },
          "includePlaceRow": {
            "title": "Place summary row",
            "type": "boolean",
            "description": "true (default) = one free type \"place\" row per place: Google's rating, listed review count, per-star histogram, how many reviews this run read and delivered, the completeness verdict (\"4,404 listed, 4,404 read — complete\"), what stopped the walk early, and a 90-day rating trend when the walk covered 180 days. For \"rating and review count only\" set maxReviewsPerPlace 1: one review is billed, the place row is free. false = review rows only.",
            "default": true
          },
          "placeIds": {
            "title": "Place ids (same as Places)",
            "type": "array",
            "description": "Alias for places that takes Google place ids only, e.g. [\"ChIJD3uTd9hx5kcR1IQvGfr8dbk\"], so the placeIds list of a compass/google-maps-reviews-scraper input or of a Google Places API export pastes straight in. Read exactly like lines in places; the same place in both is read once.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "startUrls": {
            "title": "Start URLs (same as Places)",
            "type": "array",
            "description": "Alias for places, for integrations that always send startUrls (Make, n8n, Zapier, a Google Sheet of links) and for input copied from compass/google-maps-reviews-scraper, e.g. [{\"url\": \"https://www.google.com/maps/place/…\"}]. Each entry is read exactly like a line in places. Compass names maxReviews, reviewsSort (newest, mostRelevant, highestRanking, lowestRanking), reviewsStartDate and language are understood too.",
            "default": [],
            "items": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "title": "URL of a web page",
                  "format": "uri"
                }
              }
            }
          },
          "sessions": {
            "title": "Parallel sessions",
            "minimum": 1,
            "maximum": 16,
            "type": "integer",
            "description": "Proxy sessions (IPs) working at once, 1 to 16, default 4. Places are read in parallel; the pages of one place in order. Raise it for hundreds of places.",
            "default": 4
          },
          "perIp": {
            "title": "Requests per second per IP",
            "type": "string",
            "description": "Requests per second per session, e.g. \"1\" (default) or \"0.5\". Lower is gentler on Google; 50 reviews come back per request.",
            "default": "1"
          },
          "proxyConfiguration": {
            "title": "Proxy",
            "type": "object",
            "description": "Apify datacenter proxies (default {\"useApifyProxy\": true}) are enough and keep the run cheap; residential is not needed. The actor rotates the IP whenever Google answers an empty or cut-down page.",
            "default": {
              "useApifyProxy": true
            }
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}