{
  "openapi": "3.1.0",
  "info": {
    "title": "Google Maps API",
    "version": "1.0.0",
    "description": "Google Maps through FetchLayer: search places by keyword and location, read a place in full with hours and attributes, collect emails, phones and social profiles from place websites, and fetch public reviews."
  },
  "servers": [
    {
      "url": "https://api.fetchlayer.dev/google-maps"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "description": "Every error, on every route. Branch on code and retryable rather than on the text; on a 5xx the text is generic. MCP tool errors carry the same fields in structuredContent, and as a JSON text block.",
        "properties": {
          "error": {
            "type": "string",
            "description": "What went wrong, in words. For a 400, what to change."
          },
          "status": {
            "type": "integer",
            "description": "The HTTP status, repeated in the body."
          },
          "code": {
            "type": "string",
            "description": "The kind of error, stable: invalid_input, unauthorized, insufficient_credits, forbidden, not_found, expired, quota_exceeded, cancelled, time_limit, temporarily_unavailable, posts_unavailable, store_unreachable, upstream_error, internal_error, tool_error. A platform may add its own; more may be added. Treat a code you do not recognise by its retryable flag."
          },
          "retryable": {
            "type": "boolean",
            "description": "Whether asking again can succeed."
          },
          "requestId": {
            "type": "string",
            "description": "This request’s id, also sent as the X-Request-Id header. Quote it when reporting a problem."
          },
          "missing": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "With invalid_input when the request's parameters are refused before the request runs: the parameters that were missing. Always present on those errors, empty when nothing was missing."
          }
        },
        "required": [
          "error",
          "code",
          "retryable",
          "requestId"
        ]
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Send your FetchLayer key as Authorization: Bearer ss-your-key."
      }
    }
  },
  "paths": {
    "/place-search": {
      "post": {
        "operationId": "place-search",
        "tags": [
          "Places"
        ],
        "summary": "Search Google Maps for places",
        "description": "Search Google Maps the way its search box does, \"coffee shops\" in \"Denver, CO\" or around a point with a radius, and get each place with its IDs, category, address, coordinates, phone, website, rating and review count, opening hours, open-now status, business status and time zone. Filter by minimum rating, open now or category, and continue with nextCursor. Billing: each Google result page returned counts as one request (pagesScraped). A search takes about 5 to 40 seconds.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "query": {
                    "type": "string",
                    "description": "What to search for, e.g. \"coffee shops\" or \"dentist\"."
                  },
                  "location": {
                    "type": "string",
                    "description": "Area to search in, as text: a city, neighborhood or address (\"Austin, TX\", \"Shoreditch, London\"). Use either location or coordinates."
                  },
                  "coordinates": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Search around a point instead: { latitude, longitude, radiusMeters } with radiusMeters 100-50000 (default 5000)."
                  },
                  "language": {
                    "type": "string",
                    "description": "Language for place names, categories and hours, as a language code (en, de, pt-BR).",
                    "example": "en"
                  },
                  "country": {
                    "type": "string",
                    "description": "Country the results are localized for, as a two-letter code (US, GB, DE). Three-letter codes (USA), English names (United States, UK) and locale tags (en-US) are also accepted.",
                    "example": "US"
                  },
                  "limit": {
                    "type": "integer",
                    "description": "Maximum places to return, 1-100.",
                    "example": "20"
                  },
                  "cursor": {
                    "type": "string",
                    "description": "nextCursor from a previous response, to continue the same search."
                  },
                  "minRating": {
                    "type": "number",
                    "description": "Only places rated at least this (1-5)."
                  },
                  "openNow": {
                    "type": "boolean",
                    "description": "Only places open at the time of the request."
                  },
                  "category": {
                    "type": "string",
                    "description": "Only places whose Google Maps category contains this text, e.g. \"Italian restaurant\" or \"bakery\"."
                  }
                },
                "additionalProperties": false,
                "required": [
                  "query"
                ]
              },
              "examples": {
                "default": {
                  "value": {
                    "query": "coffee shops",
                    "location": "Denver, CO",
                    "limit": 5
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "entityType": {
                      "type": "string",
                      "description": "Always gmaps-place-search."
                    },
                    "query": {
                      "type": "string",
                      "description": "The search that ran, with location, coordinates, language, country and filters echoed."
                    },
                    "places": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true,
                        "properties": {
                          "placeId": {
                            "type": "string",
                            "description": "Google place ID (ChIJ…), with featureId (0x…:0x…) and cid alongside it."
                          },
                          "name": {
                            "type": "string",
                            "description": "The place name, with category and categories."
                          },
                          "address": {
                            "type": "string",
                            "description": "The full address; addressComponents splits it into neighborhood, street, city, postalCode, state and countryCode."
                          },
                          "coordinates": {
                            "type": "object",
                            "additionalProperties": true,
                            "description": "latitude and longitude."
                          },
                          "phone": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The phone number as Google shows it, with phoneInternational in E.164 form."
                          },
                          "website": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The website listed on the place."
                          },
                          "rating": {
                            "type": [
                              "number",
                              "null"
                            ],
                            "description": "Average rating, with reviewCount alongside it."
                          },
                          "priceLevel": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Price level, only when Google shows one."
                          },
                          "openingHours": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "additionalProperties": true
                            },
                            "description": "Hours by day, each with day and hours[]."
                          },
                          "openNow": {
                            "type": [
                              "boolean",
                              "null"
                            ],
                            "description": "Whether it is open at the time of the request, with currentStatus as Google words it (e.g. \"Open · Closes 5 PM\")."
                          },
                          "businessStatus": {
                            "type": "string",
                            "description": "OPERATIONAL, CLOSED_TEMPORARILY or CLOSED_PERMANENTLY."
                          },
                          "timezone": {
                            "type": "string",
                            "description": "IANA time zone, e.g. America/Denver."
                          },
                          "googleMapsUrl": {
                            "type": "string",
                            "description": "Link to the place on Google Maps, with thumbnailUrl for its photo."
                          }
                        }
                      },
                      "description": "The places, in Google Maps order."
                    },
                    "placeCount": {
                      "type": "number",
                      "description": "Places in this response."
                    },
                    "nextCursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Pass back as cursor to continue, or null when there are no more."
                    },
                    "pagesScraped": {
                      "type": "number",
                      "description": "Google result pages returned. Each counts as one request against your plan."
                    }
                  },
                  "additionalProperties": true
                },
                "examples": {
                  "default": {
                    "value": {
                      "entityType": "gmaps-place-search",
                      "query": "coffee shops",
                      "location": "Denver, CO",
                      "coordinates": null,
                      "language": "en",
                      "country": "US",
                      "filters": {},
                      "placeCount": 5,
                      "places": [
                        {
                          "placeId": "ChIJ4YBYuiB5bIcR4CF00Xm9cC0",
                          "featureId": "0x876c7920ba5880e1:0x2d70bd79d17421e0",
                          "cid": "3274325260001092064",
                          "name": "Little Owl Coffee - Tremont",
                          "category": "Cafe",
                          "categories": [
                            "Cafe"
                          ],
                          "address": "410 17th St, Denver, CO 80202",
                          "addressComponents": {
                            "neighborhood": "Central Business District",
                            "street": "410 17th St",
                            "city": "Denver",
                            "postalCode": "80202",
                            "state": "Colorado",
                            "countryCode": "US"
                          },
                          "coordinates": {
                            "latitude": 39.744006299999995,
                            "longitude": -104.9889953
                          },
                          "plusCode": null,
                          "phone": null,
                          "phoneInternational": null,
                          "website": "http://littleowlcoffee.com/",
                          "rating": 4.6,
                          "reviewCount": 168,
                          "priceLevel": null,
                          "openingHours": [
                            {
                              "day": "Monday",
                              "hours": [
                                "7 AM–5 PM"
                              ]
                            },
                            {
                              "day": "Tuesday",
                              "hours": [
                                "7 AM–5 PM"
                              ]
                            }
                          ],
                          "currentStatus": "Open · Closes 5 PM",
                          "openNow": true,
                          "businessStatus": "OPERATIONAL",
                          "timezone": "America/Denver",
                          "googleMapsUrl": "https://www.google.com/maps/place/?q=place_id:ChIJ4YBYuiB5bIcR4CF00Xm9cC0",
                          "thumbnailUrl": "https://lh3.googleusercontent.com/gps-cs-s/AHRPTWmemx6efUuGv…"
                        }
                      ],
                      "nextCursor": "eyJvIjowLCJzIjo1fQ",
                      "pagesScraped": 1,
                      "scrapedAt": "2026-09-15T21:17:18.537Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "invalid_input: the request needs fixing; error names the field.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "unauthorized: the API key is missing or not valid.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "insufficient_credits: no credits, trial or monthly allowance left.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "forbidden: this key or account is not allowed this request.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "quota_exceeded: a request-rate limit was reached.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "temporarily_unavailable, time_limit or (on a store route) store_unreachable: ask again (with time_limit, allow more time). Retryable.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/place-details": {
      "post": {
        "operationId": "place-details",
        "tags": [
          "Places"
        ],
        "summary": "Get one Google Maps place in full",
        "description": "Read one place from its place ID or Maps URL, in the same forms reviews accepts: IDs, category, address, coordinates, plus code, phone, website, rating and review count, hours, open-now and business status, time zone, Google’s description of the place, and its attributes grouped by section (accessibility, amenities, payments and so on). Bills one request.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "placeIdOrUrl": {
                    "type": "string",
                    "description": "A ChIJ place ID, a hex feature ID (0x…:0x…), a Google Maps place URL, a CID URL (?cid=…), or a maps.app.goo.gl / goo.gl/maps short link."
                  },
                  "language": {
                    "type": "string",
                    "description": "Language for place names, categories and hours, as a language code (en, de, pt-BR).",
                    "example": "en"
                  },
                  "country": {
                    "type": "string",
                    "description": "Country the results are localized for, as a two-letter code (US, GB, DE). Three-letter codes (USA), English names (United States, UK) and locale tags (en-US) are also accepted.",
                    "example": "US"
                  }
                },
                "additionalProperties": false,
                "required": [
                  "placeIdOrUrl"
                ]
              },
              "examples": {
                "default": {
                  "value": {
                    "placeIdOrUrl": "0x47e61d19ca7ae2bd:0x57faf8cb6310e660"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "entityType": {
                      "type": "string",
                      "description": "Always gmaps-place-details."
                    },
                    "place": {
                      "type": "object",
                      "additionalProperties": true,
                      "description": "The place.",
                      "properties": {
                        "placeId": {
                          "type": "string",
                          "description": "Google place ID (ChIJ…), with featureId (0x…:0x…) and cid alongside it."
                        },
                        "name": {
                          "type": "string",
                          "description": "The place name, with category and categories."
                        },
                        "address": {
                          "type": "string",
                          "description": "The full address; addressComponents splits it into neighborhood, street, city, postalCode, state and countryCode."
                        },
                        "coordinates": {
                          "type": "object",
                          "additionalProperties": true,
                          "description": "latitude and longitude."
                        },
                        "phone": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The phone number as Google shows it, with phoneInternational in E.164 form."
                        },
                        "website": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The website listed on the place."
                        },
                        "rating": {
                          "type": [
                            "number",
                            "null"
                          ],
                          "description": "Average rating, with reviewCount alongside it."
                        },
                        "priceLevel": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Price level, only when Google shows one."
                        },
                        "openingHours": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "description": "Hours by day, each with day and hours[]."
                        },
                        "openNow": {
                          "type": [
                            "boolean",
                            "null"
                          ],
                          "description": "Whether it is open at the time of the request, with currentStatus as Google words it (e.g. \"Open · Closes 5 PM\")."
                        },
                        "businessStatus": {
                          "type": "string",
                          "description": "OPERATIONAL, CLOSED_TEMPORARILY or CLOSED_PERMANENTLY."
                        },
                        "timezone": {
                          "type": "string",
                          "description": "IANA time zone, e.g. America/Denver."
                        },
                        "googleMapsUrl": {
                          "type": "string",
                          "description": "Link to the place on Google Maps, with thumbnailUrl for its photo."
                        },
                        "plusCode": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The Open Location Code (plus code)."
                        },
                        "description": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Google’s short description of the place."
                        },
                        "attributes": {
                          "type": "object",
                          "additionalProperties": true,
                          "description": "Attributes grouped by section, e.g. { Accessibility: [\"Wheelchair accessible entrance\"] }."
                        }
                      }
                    },
                    "pagesScraped": {
                      "type": "number",
                      "description": "Always 1."
                    }
                  },
                  "additionalProperties": true
                },
                "examples": {
                  "default": {
                    "value": {
                      "entityType": "gmaps-place-details",
                      "placeIdOrUrl": "0x47e61d19ca7ae2bd:0x57faf8cb6310e660",
                      "language": "en",
                      "country": "US",
                      "place": {
                        "placeId": "ChIJveJ6yhkd5kcRYOYQY8v4-lc",
                        "featureId": "0x47e61d19ca7ae2bd:0x57faf8cb6310e660",
                        "cid": "6339652977901495904",
                        "name": "Disneyland Paris",
                        "category": "Theme park",
                        "categories": [
                          "Theme park",
                          "Amusement center",
                          "Amusement park",
                          "Country club"
                        ],
                        "address": "Bd de Parc, 77700 Coupvray, France",
                        "addressComponents": {
                          "neighborhood": null,
                          "street": "Bd de Parc",
                          "city": "Coupvray",
                          "postalCode": "77700",
                          "state": null,
                          "countryCode": "FR"
                        },
                        "coordinates": {
                          "latitude": 48.8673858,
                          "longitude": 2.7835929999999998
                        },
                        "plusCode": "8FW4VQ8M+XC",
                        "phone": "+33 9 69 32 60 66",
                        "phoneInternational": "+33969326066",
                        "website": "https://www.disneylandparis.com/",
                        "rating": 4.5,
                        "reviewCount": 325039,
                        "priceLevel": null,
                        "openingHours": [
                          {
                            "day": "Monday",
                            "hours": [
                              "9:30 AM–9 PM"
                            ]
                          },
                          {
                            "day": "Tuesday",
                            "hours": [
                              "9:30 AM–9 PM"
                            ]
                          }
                        ],
                        "currentStatus": "Closed · Opens 9:30 AM Wed",
                        "openNow": false,
                        "businessStatus": "OPERATIONAL",
                        "timezone": "Europe/Paris",
                        "googleMapsUrl": "https://www.google.com/maps/place/?q=place_id:ChIJveJ6yhkd5kcRYOYQY8v4-lc",
                        "thumbnailUrl": "https://lh3.googleusercontent.com/gps-cs-s/AHRPTWltJ2lrutCf4…",
                        "description": "Theme park complex featuring family-friendly rides, shows and costumed characters, plus hotels.",
                        "attributes": {
                          "Accessibility": [
                            "Wheelchair accessible entrance",
                            "Wheelchair accessible parking lot",
                            "Wheelchair accessible restroom",
                            "Wheelchair accessible seating"
                          ]
                        }
                      },
                      "pagesScraped": 1,
                      "scrapedAt": "2026-09-15T21:17:19.663Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "invalid_input: the request needs fixing; error names the field.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "unauthorized: the API key is missing or not valid.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "insufficient_credits: no credits, trial or monthly allowance left.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "forbidden: this key or account is not allowed this request.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "quota_exceeded: a request-rate limit was reached.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "temporarily_unavailable, time_limit or (on a store route) store_unreachable: ask again (with time_limit, allow more time). Retryable.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/place-contacts": {
      "post": {
        "operationId": "place-contacts",
        "tags": [
          "Places"
        ],
        "summary": "Collect contact details from place websites",
        "description": "The second step after /place-search: read businesses’ own websites for email addresses, phone numbers and social profiles. Pass places (any place reference, such as the placeId values from a search) and/or websites (the website values from a search, which is cheaper because no lookup is needed), at least 1 and at most 20 combined. Items come back in input order, places first, each with a status. Billing: pagesScraped is 1 per website that answered (any HTTP response, including a 403 or 404; timeouts, unreachable sites and social-profile URLs are free) plus 1 per place whose website had to be looked up. A place without a website is free, lookup included, and a website shared by several items is billed once. Twenty items can take up to about 100 seconds. A malformed place is a 400 naming its index, e.g. places[1].",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "places": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Places to collect contacts for: ChIJ place IDs, hex feature IDs, Google Maps place URLs, CID URLs or short links. Required unless websites is given; at most 20 combined with websites."
                  },
                  "websites": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Business websites to read directly, such as the website values from /place-search. Required unless places is given; a request with neither is a 400."
                  },
                  "language": {
                    "type": "string",
                    "description": "Language for place names, categories and hours, as a language code (en, de, pt-BR).",
                    "example": "en"
                  },
                  "country": {
                    "type": "string",
                    "description": "Country the results are localized for, as a two-letter code (US, GB, DE). Three-letter codes (USA), English names (United States, UK) and locale tags (en-US) are also accepted.",
                    "example": "US"
                  },
                  "format": {
                    "type": "string",
                    "description": "json or markdown, in any case; any other value is a 400. Over MCP, markdown returns the result rendered as text; the REST API accepts it and returns JSON.",
                    "example": "json"
                  }
                },
                "additionalProperties": false
              },
              "examples": {
                "default": {
                  "value": {
                    "places": [
                      "ChIJ4YBYuiB5bIcR4CF00Xm9cC0"
                    ],
                    "websites": [
                      "http://www.scr3amnsugar.com/"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "entityType": {
                      "type": "string",
                      "description": "Always gmaps-place-contacts."
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true,
                        "properties": {
                          "input": {
                            "type": "object",
                            "additionalProperties": true,
                            "description": "What was asked for: type (place or website) and value."
                          },
                          "place": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "additionalProperties": true,
                            "description": "For a place input, the place that was looked up: placeId, name and website. null for a website input."
                          },
                          "website": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The website that was read."
                          },
                          "contacts": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "additionalProperties": true,
                            "description": "emails[], phones[], socials (facebook, instagram, linkedin, x, youtube, tiktok, pinterest, each a list) and sourcePages[], the pages they were found on. null when nothing could be read."
                          },
                          "status": {
                            "type": "string",
                            "description": "found, none (the site was read and had no contacts), no_website, blocked, unreachable, timeout or not_found. When website is null, blocked, unreachable and timeout refer to the place lookup."
                          }
                        }
                      },
                      "description": "One item per input, in input order: places first, then websites."
                    },
                    "itemCount": {
                      "type": "number",
                      "description": "Items in this response."
                    },
                    "websitesFetched": {
                      "type": "number",
                      "description": "Websites that answered."
                    },
                    "placeLookups": {
                      "type": "number",
                      "description": "Places whose website had to be looked up first."
                    },
                    "pagesScraped": {
                      "type": "number",
                      "description": "websitesFetched plus placeLookups. Each counts as one request against your plan."
                    }
                  },
                  "additionalProperties": true
                },
                "examples": {
                  "default": {
                    "value": {
                      "entityType": "gmaps-place-contacts",
                      "itemCount": 2,
                      "items": [
                        {
                          "input": {
                            "type": "place",
                            "value": "ChIJ4YBYuiB5bIcR4CF00Xm9cC0"
                          },
                          "place": {
                            "placeId": "ChIJ4YBYuiB5bIcR4CF00Xm9cC0",
                            "name": "Little Owl Coffee - Tremont",
                            "website": "http://littleowlcoffee.com/"
                          },
                          "website": "http://littleowlcoffee.com/",
                          "contacts": {
                            "emails": [],
                            "phones": [],
                            "socials": {
                              "facebook": [],
                              "instagram": [
                                "https://instagram.com/littleowlcoffee"
                              ],
                              "linkedin": [],
                              "x": [],
                              "youtube": [],
                              "tiktok": [],
                              "pinterest": []
                            },
                            "sourcePages": [
                              "https://www.littleowlcoffee.com/",
                              "https://www.littleowlcoffee.com/contact"
                            ]
                          },
                          "status": "found"
                        },
                        {
                          "input": {
                            "type": "website",
                            "value": "http://www.scr3amnsugar.com/"
                          },
                          "place": null,
                          "website": "http://www.scr3amnsugar.com/",
                          "contacts": {
                            "emails": [],
                            "phones": [],
                            "socials": {
                              "facebook": [
                                "https://facebook.com/scr3amnsugar"
                              ],
                              "instagram": [
                                "https://instagram.com/scr3amnsugar"
                              ],
                              "linkedin": [],
                              "x": [],
                              "youtube": [],
                              "tiktok": [
                                "https://tiktok.com/@scr3amnsugar"
                              ],
                              "pinterest": []
                            },
                            "sourcePages": [
                              "https://www.scr3amnsugar.com/"
                            ]
                          },
                          "status": "found"
                        }
                      ],
                      "websitesFetched": 2,
                      "placeLookups": 1,
                      "pagesScraped": 3,
                      "scrapedAt": "2026-09-15T21:31:02.121Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "invalid_input: the request needs fixing; error names the field.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "unauthorized: the API key is missing or not valid.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "insufficient_credits: no credits, trial or monthly allowance left.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "forbidden: this key or account is not allowed this request.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "quota_exceeded: a request-rate limit was reached.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "temporarily_unavailable, time_limit or (on a store route) store_unreachable: ask again (with time_limit, allow more time). Retryable.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/reviews": {
      "post": {
        "operationId": "reviews",
        "tags": [
          "Reviews"
        ],
        "summary": "Fetch place reviews",
        "description": "Fetch public reviews for a Google Maps place using its place ID or Maps URL. Control pagination, total results, reviews per page, and sorting.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "placeIdOrUrl": {
                    "type": "string",
                    "description": "A ChIJ place ID, a hex place ID (0x…:0x…), a Google Maps place URL, a CID URL (?cid=…), or a maps.app.goo.gl / goo.gl/maps short link."
                  },
                  "pages": {
                    "type": "integer",
                    "description": "How many pages of reviews to return.",
                    "example": "10"
                  },
                  "maxReviews": {
                    "type": "integer",
                    "description": "Maximum number of reviews to return.",
                    "example": "10000"
                  },
                  "reviewsPerPage": {
                    "type": "integer",
                    "description": "Reviews requested per page (1-20). A ceiling, not a promise: Google varies how many reviews it shows publicly, so a page can come back with fewer — the same request may return 20 one run and 5 the next.",
                    "example": "20"
                  },
                  "sortBy": {
                    "type": "string",
                    "description": "Sort order: mostRelevant, newest, highestRating, or lowestRating.",
                    "example": "mostRelevant"
                  }
                },
                "additionalProperties": false,
                "required": [
                  "placeIdOrUrl"
                ]
              },
              "examples": {
                "default": {
                  "value": {
                    "placeIdOrUrl": "ChIJLU7jZClu5kcR4PcOOO6p3I0",
                    "pages": 1,
                    "maxReviews": 20,
                    "reviewsPerPage": 20,
                    "sortBy": "mostRelevant"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "reviews": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      },
                      "description": "Public review records returned for the requested place."
                    }
                  },
                  "additionalProperties": true
                },
                "examples": {
                  "default": {
                    "value": {
                      "reviews": []
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "invalid_input: the request needs fixing; error names the field.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "unauthorized: the API key is missing or not valid.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "insufficient_credits: no credits, trial or monthly allowance left.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "forbidden: this key or account is not allowed this request.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "quota_exceeded: a request-rate limit was reached.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "temporarily_unavailable, time_limit or (on a store route) store_unreachable: ask again (with time_limit, allow more time). Retryable.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    }
  }
}