# ScrapeMapsAPI: Google Maps places & reviews API ScrapeMapsAPI is a REST API for Google Maps places and reviews: text search, place details (address, coordinates, opening hours, contacts, attributes, photos) and every review of a place (not just 5), paged with cursors, sortable and translated. Billing is per call: every successful call costs 1 credit, whatever it returns (a page of up to 20 places or 20 reviews, one place's details, one identifier/URL resolution). 200 free calls per month, then $3 per 1,000 calls, down to $1.50 with credit packs valid for 12 months; only HTTP 200 responses are billed. Authenticated with an API key (X-API-Key header or Authorization: Bearer). Official SDKs for Python and TypeScript, and an MCP server for AI assistants (local, or remote as a Claude/ChatGPT connector with OAuth sign-in). Calls are synchronous: you get the data in the HTTP response. It is a simpler alternative to the official Google Places API (which returns at most 5 reviews per place) and to scraping services billed per batch job. Base URL: https://api.scrapemapsapi.com (all paths start with /v1). Authentication: send your API key in the `X-API-Key` header, or as `Authorization: Bearer `. Create an account at https://scrapemapsapi.com/auth/sign-up; keys are managed in the dashboard. ## Pricing - Every successful (HTTP 200) call costs 1 credit, whatever it returns; an empty result is a call too. Errors are free. - 1,000 credits (calls) = $3 at the list price; credit packs from 10,000 credits ($27) to 10,000,000 credits ($15,000, i.e. $1.50 per 1,000 calls). Purchased credits are valid for 12 months from purchase. No subscription. - 200 free calls every month, no credit card required. - A call returns one page: up to 20 places or 20 reviews. The next page is a new call (1 credit). With full pages, 1,000 places or reviews cost $0.15 ($0.075 with the biggest pack). | Call | Credits | |---|---| | Search | 1 per call (up to 20 places) | | Place details | 1 | | Reviews | 1 per call (up to 20 reviews) | | Resolve | 1 | Details: https://scrapemapsapi.com/pricing ## Endpoints ### GET /v1/places/search Text search on Google Maps, optionally biased to an area. Sponsored results are skipped. Landing page: https://scrapemapsapi.com/google-maps-places-api Parameters: - `q` (required, 1-300 characters): what to search, e.g. `trattoria in Florence` - `language`: language of the results, default `en` (e.g. `it`, `pt-BR`) - `region`: 2-letter country code, default `us` - `lat`, `lng`: centre of the area (both or neither, otherwise 400 `invalid_location`) - `radius_km`: radius of the area, greater than 0 and up to 100 - `limit`: places per page, 1-20, default 20 - `cursor`: `pagination.next_cursor` of the previous page Response: `{"data": [PlaceSummary], "pagination": {"next_cursor", "has_more"}, "meta": {"credits_used", "cached", "query", "language", "region"}}` ### GET /v1/places/{place} Full details of one place. `place` is a place ID (`ChIJ...`), a CID (decimal, as in `maps?cid=`) or a feature ID (`0x...:0x...`). Landing page: https://scrapemapsapi.com/google-maps-place-details-api Parameters: `language` (default `en`), `region` (default `us`). Response: `{"data": Place, "meta": {"credits_used": 1, "cached", "language"}}` ### GET /v1/places/{place}/reviews All reviews of a place, paged with cursors. Landing page: https://scrapemapsapi.com/google-maps-reviews-api Parameters: - `sort`: `relevant` (default), `newest`, `highest`, `lowest` - `language`: language of relative dates and translation target, default `en` - `original_language`: only reviews originally written in this language, e.g. `it` (a filtered page can hold fewer than `limit` reviews) - `limit`: reviews per page, 1-20, default 20 (one page of the review feed per call) - `cursor`: `pagination.next_cursor` of the previous page Response: `{"data": [Review], "pagination": {"next_cursor", "has_more"}, "meta": {"credits_used", "cached", "place_id", "cid", "sort", "language", "original_language"}}` ### GET /v1/places/resolve Converts any identifier or Google Maps URL (including `maps.app.goo.gl` short links) into all identifiers of the place. Parameters: `input` (required, up to 2,000 characters). Response: `{"data": {"place_id", "cid", "feature_id", "google_maps_url"}, "meta": {"credits_used", "cached"}}` ## Objects PlaceSummary (search): `id` (place ID or null), `ids` {place_id, cid, feature_id, google_maps_url}, `name`, `categories[]`, `address` {formatted, street, postal_code, city, region, country_code}, `location` {lat, lng}, `rating`, `review_count`, `phone`, `website`, `status` (operational, temporarily_closed, permanently_closed or null). Place (details) = PlaceSummary plus `local_name`, `phone_international`, `plus_code`, `timezone`, `description`, `opening_hours` {weekly[{day, closed, open_24h, periods[{open, close}], text}], status_text}, `attributes` {group: [labels]}, `photos[]` {url, width, height}, `booking_links[]` {url, domain}, `knowledge_graph_id`. Popular times and price level are not available. Review: `id`, `rating` (1-5), `published_at` (ISO 8601, UTC), `relative_date`, `language`, `text`, `translated_text`, `author` {id}, `owner_response` {text, translated_text, relative_date}, `photos[]`, `details` (structured answers such as price per person, food, service), `source`. Review authors are pseudonymous: `author.id` is a stable keyed hash. Names, profile photos and profile links are never returned. ## Pagination Search and reviews return `pagination`. While `has_more` is true, repeat the same request with `cursor` set to `next_cursor`. Cursors are opaque and signed; a cursor used with another query or place is refused with 400 `invalid_cursor`. ## Response headers - `X-Credits-Used`: credits charged for the call - `X-Credits-Remaining`: credits left on the account - `X-Cache`: HIT or MISS - `X-Processing-Time`: milliseconds - `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` ## Errors Every error is `{"detail": {"error": "", "message": ""}}`, for example: ```json {"detail": {"error": "place_not_found", "message": "Google has no place with this identifier"}} ``` Errors are never billed. Codes: - 400 `invalid_place_id`: the place is not a place ID, CID or feature ID, or the URL does not identify a place - 400 `invalid_cursor`: malformed cursor, or a cursor of another query or place - 400 `invalid_location`: only one of lat and lng - 401 `missing_api_key`: no X-API-Key header and no Bearer token - 401 `invalid_api_key`: unknown or disabled key - 402 `insufficient_credits`: not enough credits; `detail` also has `available` and `required` - 404 `place_not_found`: no place with this identifier (or the short link does not exist) - 422: invalid parameter (FastAPI validation); here `detail` is a list of `{"loc", "msg", "type"}` objects, e.g. `{"detail": [{"loc": ["query", "limit"], "msg": "Input should be less than or equal to 20", "type": "less_than_equal"}]}` - 429 `rate_limit_exceeded`: more than 500 requests per minute; `insufficient_credits_retry_later`: repeated calls without credits, the key is paused. Both send `Retry-After` (seconds) and `detail.retry_after` - 500 `internal_server_error`: unexpected error - 502 `upstream_error` (or `proxy_error` when following a short link fails): retry with backoff - 503 `upstream_unavailable`: Google Maps temporarily unreachable; retry in a minute Retry only 429, 502 and 503. Full list: https://scrapemapsapi.com/docs/errors ## Example (cURL) ``` curl "https://api.scrapemapsapi.com/v1/places/search?q=trattoria%20in%20Florence®ion=it&limit=5" -H "X-API-Key: " curl "https://api.scrapemapsapi.com/v1/places/ChIJ8cLgoQNUKhMReGlaTjwrH40/reviews?sort=newest&limit=20" -H "X-API-Key: " ``` ## Example (Python, requests) ```python import requests API = "https://api.scrapemapsapi.com/v1" HEADERS = {"X-API-Key": ""} params = {"sort": "newest", "limit": 20} reviews = [] while True: r = requests.get(f"{API}/places/ChIJ8cLgoQNUKhMReGlaTjwrH40/reviews", headers=HEADERS, params=params) if r.status_code != 200: raise RuntimeError(r.json()["detail"]) page = r.json() reviews += page["data"] if not page["pagination"]["has_more"]: break params["cursor"] = page["pagination"]["next_cursor"] ``` ## SDKs - Python: `pip install scrapemapsapi`; `from scrapemapsapi import ScrapeMapsAPI`; `client.places.search(q, ...)`, `client.places.get(place)`, `client.places.reviews(place, sort=..., limit=..., cursor=...)`, `client.places.iter_reviews(place, max_items=...)`, `client.places.iter_search(q, ...)`, `client.places.resolve(input)`; async: `AsyncScrapeMapsAPI`. Errors are typed exceptions with `code`, `status_code` and `retry_after`. - TypeScript: `npm install scrapemapsapi`; `import { ScrapeMapsAPI } from 'scrapemapsapi'`; `client.places.search({ q })`, `client.places.get(place)`, `client.places.reviews(place, { sort, limit, cursor })`, `client.places.iterReviews(place, { maxItems })`, `client.places.iterSearch({ q })`, `client.places.resolve(input)`. Guide: https://scrapemapsapi.com/docs/sdks ## MCP server A local MCP server: `uvx scrapemapsapi-mcp` (PyPI) or `npx -y scrapemapsapi-mcp` (npm), with `SCRAPEMAPSAPI_API_KEY` in the environment. Tools: `search_places`, `get_place`, `get_reviews`, `resolve_place`. Works with Claude Desktop, Cursor and Claude Code (`claude mcp add scrapemapsapi -e SCRAPEMAPSAPI_API_KEY= -- uvx scrapemapsapi-mcp`). Tool calls are billed like API calls. Guide: https://scrapemapsapi.com/docs/mcp Remote MCP server (connector): add `https://api.scrapemapsapi.com/mcp` as a custom connector in Claude (web, desktop, mobile) or ChatGPT, or `claude mcp add --transport http scrapemapsapi https://api.scrapemapsapi.com/mcp` in Claude Code, then sign in with your ScrapeMapsAPI account and allow access (OAuth 2.1, no API key). Same tools; calls use the account's credits with the same billing. Connected apps can be disconnected from the dashboard. ## Free tool https://scrapemapsapi.com/google-maps-reviews-scraper: paste a Google Maps link or place ID and see the place card with its 10 newest reviews, free and without an account. ## Pages - [Google Maps Reviews API](https://scrapemapsapi.com/google-maps-reviews-api): Every review of a place, paged with cursors, sortable, filtered by language and translated. - [Google Maps Places API](https://scrapemapsapi.com/google-maps-places-api): Search places by text, optionally around a point, 20 per page with cursor paging. - [Google Maps Place Details API](https://scrapemapsapi.com/google-maps-place-details-api): Address, coordinates, opening hours, phone, website, attributes and photos of one place. - [Getting started](https://scrapemapsapi.com/docs): Create an API key and make a first request. - [API reference](https://scrapemapsapi.com/docs/api): Every endpoint, parameter, response field and cursor paging. - [Authentication](https://scrapemapsapi.com/docs/authentication): API keys, the X-API-Key header and Bearer tokens. - [Code examples](https://scrapemapsapi.com/docs/examples): cURL, Python and JavaScript examples for every endpoint. - [Errors](https://scrapemapsapi.com/docs/errors): HTTP status codes, error codes and when to retry. - [Python & TypeScript SDKs](https://scrapemapsapi.com/docs/sdks): The official SDKs, with typed models and auto-pagination. - [MCP server](https://scrapemapsapi.com/docs/mcp): Google Maps places and reviews in Claude, Cursor and other MCP clients.