{
  "openapi": "3.0.1",
  "info": {
    "title": "Google Maps Reviews Scraper - Ratings, Owner Replies & Dates",
    "description": "Scrape Google Maps reviews of any place: star rating, full text, exact publish and edit dates, owner reply with date, photos, reviewer name, review count and Local Guide level. Paste place URLs, place IDs, CIDs or a business name. Newest-first, star and date filters, monitor mode for scheduled runs.",
    "version": "0.1",
    "x-build-id": "XySefRXGje61PeH0K"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/topapi~google-maps-reviews-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-topapi-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/topapi~google-maps-reviews-scraper/runs": {
      "post": {
        "operationId": "runs-sync-topapi-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/topapi~google-maps-reviews-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-topapi-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": {
          "placeUrls": {
            "title": "🔗 Place URLs, Place IDs or CIDs",
            "type": "array",
            "description": "One place per line, any of: a Google Maps place URL (https://www.google.com/maps/place/Katz's+Delicatessen/...), a Place ID (ChIJN1t_tDeuEmsRUsoyG83frY4), a CID (10281501156462635602), a feature id (0x89c2598f7ff4aa09:0x313547e757cb8cea) or a maps.app.goo.gl share link.",
            "items": {
              "type": "string"
            }
          },
          "searchQueries": {
            "title": "🔎 Business names to look up",
            "type": "array",
            "description": "Optional. A business name with its city, e.g. \"Katz's Delicatessen New York\" or \"The Ritz London\". Each query resolves to its top Google Maps match and that place's reviews are scraped. Generic queries (\"plumber in Austin\") take the first result only.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "mode": {
            "title": "⚡ Mode",
            "enum": [
              "full",
              "quick"
            ],
            "type": "string",
            "description": "Full walks Google's complete review feed 20 at a time up to Max reviews per place. Quick returns only the 5-8 reviews Google embeds in the place record (its 'most relevant' pick), in about 2 seconds per place and without a browser - ideal for a rating-plus-highlights snapshot of many places. Sorting, date filters and monitor mode need Full.",
            "default": "full"
          },
          "reviewsSort": {
            "title": "↕️ Sort reviews by",
            "enum": [
              "newest",
              "mostRelevant",
              "highestRanking",
              "lowestRanking"
            ],
            "type": "string",
            "description": "Newest first walks the complete review history in date order and lets the date filters stop early. Most relevant may expose only a ranked subset on very large places.",
            "default": "newest"
          },
          "language": {
            "title": "🌐 Language",
            "enum": [
              "en",
              "de",
              "es",
              "fr",
              "it",
              "pt",
              "pt-BR",
              "nl",
              "pl",
              "cs",
              "sv",
              "da",
              "nb",
              "fi",
              "tr",
              "ru",
              "uk",
              "el",
              "hu",
              "ro",
              "ja",
              "ko",
              "zh-CN",
              "zh-TW",
              "th",
              "vi",
              "id",
              "ms",
              "hi",
              "ar",
              "he"
            ],
            "type": "string",
            "description": "Language of the interface strings and of Google's automatic translations: a review written in another language comes back with both the original text and the translation into this language (fields text / textTranslated).",
            "default": "en"
          },
          "region": {
            "title": "📍 Region",
            "pattern": "^[A-Za-z]{2}$",
            "type": "string",
            "description": "Two-letter country code Google is asked from, e.g. us, gb, de. Affects regional formatting (dates, currency in \"price per person\"). Keep us unless you need another market.",
            "default": "us"
          },
          "reviewsNewerThan": {
            "title": "📅 Only reviews newer than",
            "type": "string",
            "description": "Absolute date (2026-09-01, 2026-09-01T12:00:00Z) or relative to now (7 days, 3 weeks, 2 months, 1 year). Leave empty for no lower bound."
          },
          "reviewsOlderThan": {
            "title": "📅 Only reviews older than",
            "type": "string",
            "description": "Absolute date or relative (e.g. 30 days). Combine with the field above for a window such as reviewsNewerThan \"2026-01-01\" + reviewsOlderThan \"2026-06-30\"."
          },
          "minStars": {
            "title": "⭐ Minimum stars",
            "minimum": 1,
            "maximum": 5,
            "type": "integer",
            "description": "Keep reviews with at least this many stars (1-5). Use minStars 1 + maxStars 3 for complaints only.",
            "default": 1
          },
          "maxStars": {
            "title": "⭐ Maximum stars",
            "minimum": 1,
            "maximum": 5,
            "type": "integer",
            "description": "Keep reviews with at most this many stars (1-5). Default 5 = no upper bound.",
            "default": 5
          },
          "withTextOnly": {
            "title": "📝 Only reviews with text",
            "type": "boolean",
            "description": "Skip star-only ratings that carry no written review (on a 120-review test sample 27% of reviews had no text).",
            "default": false
          },
          "reviewsFilterString": {
            "title": "🔤 Keyword filter",
            "type": "string",
            "description": "Keep only reviews whose text (or owner reply) contains this word or phrase, case-insensitive, e.g. \"parking\" or \"wait time\". Several words separated by commas = any of them.",
            "default": ""
          },
          "includePlaceSummary": {
            "title": "🏢 Include place summary row",
            "type": "boolean",
            "description": "Adds one row of type \"place\" per place: Google rating, total review count, address, phone, website, categories, coordinates, Place ID / CID, plus how many reviews this run read and delivered. Included in the place fee (place-scraped).",
            "default": false
          },
          "monitorMode": {
            "title": "🔁 Only new reviews since the last run",
            "type": "boolean",
            "description": "Remembers, per place, which reviews were already delivered (in the named key-value store below) and returns only new ones, newest first. A place checked with nothing new delivers nothing and is billed only its place fee (place-scraped), the check itself.",
            "default": false
          },
          "monitorStoreName": {
            "title": "🗄️ Monitor memory name",
            "pattern": "^[a-zA-Z0-9-]{1,63}$",
            "type": "string",
            "description": "Name of the key-value store that keeps the per-place memory for monitor mode. Give each separate feed (a client, a Slack channel) its own name so they do not hide reviews from each other. Letters, digits and hyphens.",
            "default": "google-maps-reviews-monitor"
          },
          "maxReviewsPerPlace": {
            "title": "🔢 Max reviews per place",
            "minimum": 0,
            "maximum": 100000,
            "type": "integer",
            "description": "Cap per place after filters (your main cost control; you pay per delivered review plus one place fee per place). 0 = every review Google serves. Google serves 20 reviews per request; a 1,000-review place takes about 15-20 seconds. Quick mode returns the 5-8 reviews Google embeds.",
            "default": 100
          },
          "personalData": {
            "title": "👤 Include reviewer details",
            "type": "boolean",
            "description": "Include the reviewer's name, profile URL, photo URL and ID (name, reviewerUrl, reviewerPhotoUrl, reviewerId). Turn off to receive anonymised rows; the review id, text, stars and dates are always included.",
            "default": true
          },
          "compact": {
            "title": "🤖 Compact output",
            "type": "boolean",
            "description": "Core fields only (reviewId, stars, text, textTranslated, publishedAtDate, name, responseFromOwnerText, reviewUrl, title, placeId): about a quarter of the bytes, sized for AI agents and MCP clients.",
            "default": false
          },
          "proxyConfiguration": {
            "title": "🌍 Proxy",
            "type": "object",
            "description": "Apify Proxy is recommended; datacenter proxies are enough (measured: Google serves the reviews feed to Apify DATACENTER and RESIDENTIAL IPs alike). One proxy session is kept for the whole run and rotated only when Google answers with an empty page or a block.",
            "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}