# Google Maps API

> Source: https://scrape.do/documentation/google-scraper-api/maps/

Scrape Google Maps search results and place details as structured JSON

![Google Maps API](/uploads/google-maps-api.svg)

The Google Maps API is a specialized plugin that searches Google Maps, extracts structured data from place details pages, and returns paginated user reviews, all as clean JSON. Instead of rendering Google Maps in a headless browser and parsing protobuf, you send a query and get back ratings, addresses, opening hours, contact info, menus, popular times, reviews, and more.

> [!NOTE]
> **Credit Usage:** Each successful request costs **10 credits**, same for Search, Place, and Reviews. For bulk processing, use the [Async API with plugins](/documentation/async-api/plugins/).

## Key Features

- **Structured JSON Output**: Get 25+ parsed fields per place including `place_id`, `data_id`, coordinates, rating, reviews count, opening hours, menu, popular times, and service options.
- **Worldwide Coverage**: Target any regional Google domain from `google.com` to `google.co.jp`, `google.de`, `google.com.tr`, and more. 150+ interface languages and 240+ country codes supported.
- **Precise Geo-Targeting**: Constrain Maps searches to a specific area with the `ll=@lat,lng,zoom` parameter. Without it, Google uses IP-based geolocation.
- **Full Place Details**: Dedicated `/place` endpoint returns enriched fields not in search results: `menu`, `popular_times`, `user_reviews`, `plus_code`, `rating_summary`, `summary`, and a full `images` array.
- **Paginated Reviews**: Fetch up to 20 reviews per request with sorting (newest, highest, lowest), topic filters, keyword search, and guided review details (food/service/atmosphere for restaurants, bed comfort/location/rooms for hotels).
- **Localized Reviews**: Non-English locales return both the original review text and a translation inline, plus guided-review `details` keys in the requested language.
- **Owner Responses & Third-Party Sources**: Business replies are returned inline. Hotels include reviews from Priceline, Tripadvisor, Booking.com, and Trip.com alongside Google reviews.
- **Pagination**: Navigate through up to 6 pages of Maps search results, or paginate reviews with `next_page_token`.
- **No Blocks or CAPTCHAs**: All anti-bot measures are handled automatically by Scrape.do.

---

## Endpoints

| Endpoint | Method | Output | Description | Details |
|----------|--------|--------|-------------|---------|
| `/plugin/google/maps/search` | GET | JSON | Search Google Maps and get a paginated list of places with ratings, addresses, and contact info | [more](/documentation/google-scraper-api/maps/search) |
| `/plugin/google/maps/place` | GET | JSON | Fetch enriched details for a single place (menu, popular times, user reviews, images) | [more](/documentation/google-scraper-api/maps/place) |
| `/plugin/google/maps/reviews` | GET | JSON | Paginated user reviews with ratings, text, images, guided details, topics, and owner responses | [more](/documentation/google-scraper-api/maps/reviews) |

### Credit Costs

| Endpoint | Credits per Request |
|----------|---------------------|
| `/plugin/google/maps/search` | 10 |
| `/plugin/google/maps/place` | 10 |
| `/plugin/google/maps/reviews` | 10 |

---

## Authentication

All requests require your Scrape.do API token passed via the `token` query parameter:

```
https://api.scrape.do/plugin/google/maps/search?token=YOUR_TOKEN&q=pizza+new+york
```

---

## Response Format

Responses are returned as **JSON**. Array fields always return `[]` when empty (never `null`). Object fields return `null` when absent.

> [!NOTE]
> Parameter keys are **case-insensitive**. You can use `q`, `Q`, `hl`, `HL`, etc.

---

## Handling Transient Empty Results

Google occasionally returns an empty result shell for a query even when the underlying place data exists. The plugin surfaces this as **`502 no results`** or, less commonly, an empty results array. These are almost always transient.

> [!WARNING]
> For paginated crawls, treat `502 no results` as a **retry-once** condition rather than a permanent empty. A single retry is usually enough to recover. Only treat a repeated failure as a true "no results" state.

---

## Error Handling

All endpoints return errors in a consistent JSON format:

```json
{
  "error": "error_code",
  "message": "Human readable error message"
}
```

### Common Error Codes

| Status | Error | Description |
|--------|-------|-------------|
| `400` | `token is required` | Missing authentication token |
| `400` | `q (search query) is required` | Missing `q` parameter (Search endpoint) |
| `400` | `place_id or data_cid is required` | Neither identifier provided (Place endpoint) |
| `400` | `data_id or place_id is required` | Neither identifier provided (Reviews endpoint) |
| `400` | `sort_by must be one of: newestFirst, ratingHigh, ratingLow` | Invalid Reviews `sort_by` value |
| `400` | `topic_id and query parameters can't be used together` | Mutually exclusive Reviews filters both supplied |
| `400` | `num must be an integer between 1 and 20` | Reviews `num` outside the accepted range |
| `400` | `invalid ll parameter` | Bad location format; expected `@lat,lng,zoom` |
| `400` | `invalid start parameter` | Start must be a non-negative multiple of 20 |
| `502` | `no results` | Google returned zero results for this query. Retry once before treating as final |
| `502` | `request failed` | Transient upstream failure. Safe to retry |
| `502` | `failed to extract search data URL` / `failed to extract place data URL` | Upstream shell did not contain the expected data URL. Retry |
| `502` | `reviews request failed` | Reviews endpoint: transient upstream failure. Retry |
| `502` | `failed to extract data_id from place` | Reviews endpoint: could not resolve `place_id` to a `data_id`. Retry or pass `data_id` directly |
| `500` | `failed to parse search results` / `failed to parse place results` / `failed to parse reviews` | Parser error on the Google response |

---