# Search Places

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

Search Google Maps and get a structured list of places as JSON

The Search endpoint performs a Google Maps search for any query and returns a paginated list of places with ratings, addresses, contact info, opening hours, and more. All results are parsed and returned as structured JSON.

---

## Endpoint

```
GET https://api.scrape.do/plugin/google/maps/search
```

---

## Request Parameters

### Required

| Parameter | Type | Description |
|-----------|------|-------------|
| `token` | string | Your Scrape.do API authentication token |
| `q` | string | Search query. URL-encode spaces and special characters. Examples: `pizza+new+york`, `dentist`, `hotels+chicago` |

### General

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `start` | integer | `0` | Result offset for pagination. Must be a non-negative multiple of 20 (`0`, `20`, `40`, `60`, `80`, `100`) |
| `ll` | string | — | Location constraint in the format `@lat,lng,zoom`. Zoom is `1z`–`21z`. Example: `@40.7128,-74.0060,13z`. Without `ll`, Google uses IP-based geolocation. |

### Localization & Geo-targeting

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `hl` | string | `en` | **Host Language.** Controls the language of the Google Maps UI and result labels. Examples: `tr`, `de`, `fr`, `ja`. [Full list →](/documentation/google-scraper-api/localization#language-parameter-hl) |
| `gl` | string | `us` | **Geo Location.** The country from whose perspective results are returned. Examples: `tr`, `de`, `gb`, `jp`. [Full list →](/documentation/google-scraper-api/localization#country-parameter-gl) |
| `google_domain` | string | `google.com` | Google domain to query. Examples: `google.com.tr`, `google.de`, `google.co.uk`. [Full list →](/documentation/google-scraper-api/localization#supported-google-domains) |

---

## Example Usage

### Step 1: Define Your Search Query

Decide what you want to find on Google Maps. This can be:
- **Category searches**: `pizza new york`, `dentist`, `coffee shops`
- **Local business lookups**: `Joe's Pizza Broadway`, `starbucks`
- **Geo-constrained searches**: use `ll=@lat,lng,zoom` to pin a specific area

### Step 2: Send the API Request

**cURL (API mode)**

```bash
curl --location --request GET 'https://api.scrape.do/plugin/google/maps/search?token=<SDO-token>&q=pizza+new+york'
```

**Python (API mode)**

```python
import requests
import json

token = "<SDO-token>"
query = "pizza+new+york"

url = f"https://api.scrape.do/plugin/google/maps/search?token={token}&q={query}"

response = requests.request("GET", url)

print(json.dumps(response.json(), indent=2))
```

**Node.js (API mode)**

```javascript
const axios = require('axios');

const token = "<SDO-token>";
const query = "pizza+new+york";

const url = `https://api.scrape.do/plugin/google/maps/search?token=${token}&q=${query}`;

axios.get(url)
  .then(response => {
    console.log(JSON.stringify(response.data, null, 2));
  })
  .catch(error => {
    console.error(error);
  });
```

*(Go, Ruby, Java, C#, PHP examples are also available on the HTML version.)*

### Step 3: Receive Structured Results

The API returns a JSON object with up to 20 places per page:

```json
{
  "search_metadata": {
    "google_maps_url": "https://www.google.com/maps/search/pizza+new+york/?gl=us&hl=en"
  },
  "search_parameters": {
    "engine": "google_maps",
    "type": "search",
    "q": "pizza new york",
    "google_domain": "google.com",
    "hl": "en",
    "gl": "us"
  },
  "search_information": {
    "local_results_state": "Results for exact spelling",
    "query_displayed": "pizza new york"
  },
  "local_results": [
    {
      "position": 1,
      "title": "Joe's Pizza",
      "place_id": "ChIJLSsVbGBZwokRR0LlGBSvMOI",
      "data_id": "0x89c259606c152b2d:0xe230af1b18e542a7",
      "data_cid": "16313085445244584615",
      "provider_id": "/g/1tdfm6_5",
      "gps_coordinates": { "latitude": 40.7306458, "longitude": -73.9969874 },
      "rating": 4.4,
      "reviews": 12847,
      "price": "$",
      "extracted_price": null,
      "type": "Pizza restaurant",
      "types": ["Pizza restaurant", "Italian restaurant"],
      "type_id": "pizza_restaurant",
      "type_ids": ["pizza_restaurant", "italian_restaurant"],
      "address": "7 Carmine St, New York, NY 10014",
      "open_state": "Open · Closes 4 AM",
      "hours": "Open · Closes 4 AM",
      "operating_hours": {
        "monday": "10 AM–4 AM",
        "tuesday": "10 AM–4 AM",
        "wednesday": "10 AM–4 AM",
        "thursday": "10 AM–4 AM",
        "friday": "10 AM–5 AM",
        "saturday": "10 AM–5 AM",
        "sunday": "10 AM–4 AM"
      },
      "phone": "(212) 366-1182",
      "website": "https://www.joespizzanyc.com/",
      "description": "No-frills, counter-serve pizzeria offering thin-crust pies.",
      "thumbnail": "https://lh3.googleusercontent.com/...",
      "service_options": { "dine_in": true, "takeout": true }
    }
  ]
}
```

---

## Response Structure

### Top-Level Fields

| Field | Type | Description |
|-------|------|-------------|
| `search_metadata` | object | Canonical Google Maps URL for the query |
| `search_parameters` | object | Echo of request parameters sent by the client |
| `search_information` | object | `local_results_state` (e.g., `"Results for exact spelling"`) and `query_displayed` |
| `local_results` | array | Places matching the query (up to 20 per page) |

---

### `local_results[]`

| Field | Type | Description |
|-------|------|-------------|
| `position` | int | Result position (1-indexed, page-adjusted: page 2 starts at 21) |
| `title` | string | Place name |
| `place_id` | string | Google Place ID (`ChIJ...` format) |
| `data_id` | string | Internal data ID (`0xHEX:0xHEX` format). Used by the [Reviews API](/documentation/google-scraper-api/maps/reviews) |
| `data_cid` | string | Numeric CID. Accepted by the Place endpoint |
| `provider_id` | string | Provider ID (`/g/...` format) |
| `gps_coordinates` | object | `{ latitude, longitude }` |
| `rating` | float | Average rating (1.0–5.0) |
| `reviews` | int | Total review count |
| `price` | string | Price level (`$`, `$$`, `$$$`, `$30–50`, `$119`) |
| `extracted_price` | int/null | First numeric price extracted (e.g., `$30–50` → `30`) |
| `type` | string | Primary place type (e.g., `"Pizza restaurant"`) |
| `types` | string[] | All place types |
| `type_id` | string | Primary type ID (e.g., `"pizza_restaurant"`) |
| `type_ids` | string[] | All type IDs |
| `address` | string | Full address |
| `open_state` | string | Current open/closed status with next change |
| `hours` | string | Same as `open_state` |
| `operating_hours` | object | Weekly hours keyed by day (localized to `hl`) |
| `phone` | string | Phone number |
| `website` | string | Website URL |
| `description` | string | Place description (when available) |
| `thumbnail` | string | Thumbnail image URL |
| `user_review` | string | Featured user review snippet (quoted) |
| `extensions` | array | Categorized extension attributes |
| `unsupported_extensions` | array | Extensions marked unavailable by Google |
| `service_options` | object | Service options as `{key: true}`, keys snake_cased (e.g., `"Dine-in"` → `"dine_in"`) |
| `order_online` | string | Order online URL (restaurants) |
| `reserve_a_table` | string | Reservation URL |
| `book_online` | string | Booking URL (hotels) |
| `amenities` | string[] | Amenities list (hotels) |
| `unclaimed_listing` | bool | `true` if the listing is unclaimed |

> [!NOTE]
> Not every field appears on every result. `operating_hours` localizes day names based on `hl`. `extracted_price` extracts the first number from the price string: `$30–50` → `30`, `$$` → `null`.

---

## Pagination

Results come in pages of up to 20. Use `start` to paginate:

| Page | `start` value |
|------|---------------|
| 1 | `0` (default) |
| 2 | `20` |
| 3 | `40` |
| 4 | `60` |
| 5 | `80` |
| 6 | `100` |

Google Maps typically returns a maximum of ~120 results (6 pages). When paginated, `position` values are adjusted: page 2 starts at position 21, page 3 at 41, etc.

```bash
# Page 1
curl "https://api.scrape.do/plugin/google/maps/search?q=pizza+new+york&token=YOUR_TOKEN"

# Page 2
curl "https://api.scrape.do/plugin/google/maps/search?q=pizza+new+york&start=20&token=YOUR_TOKEN"

# Page 3
curl "https://api.scrape.do/plugin/google/maps/search?q=pizza+new+york&start=40&token=YOUR_TOKEN"
```

> [!WARNING]
> Deep-page requests can occasionally return `502 no results` even when more data exists. Retry once before treating it as the true end of the result set.

---

## Geo-targeting with `ll`

The `ll` parameter pins the search to a specific lat/lng/zoom. It takes the form `@lat,lng,zoomz` where `zoom` is an integer from 1 (world) to 21 (building level) followed by `z`.

```bash
# Restaurants near Times Square, New York
curl "https://api.scrape.do/plugin/google/maps/search?q=restaurant&ll=@40.7580,-73.9855,15z&token=YOUR_TOKEN"

# Coffee shops near the Ferry Building, San Francisco
curl "https://api.scrape.do/plugin/google/maps/search?q=coffee&ll=@37.7955,-122.3937,14z&token=YOUR_TOKEN"
```

Without `ll`, Google uses IP-based geolocation of the proxy network. Results default to a US-wide view when `gl=us`.

---

## Example Requests

**Basic search:**
```
/plugin/google/maps/search?token=TOKEN&q=pizza+new+york
```

**Search with location:**
```
/plugin/google/maps/search?token=TOKEN&q=dentist&ll=@40.7128,-74.0060,13z
```

**French locale:**
```
/plugin/google/maps/search?token=TOKEN&q=restaurant+paris&hl=fr&gl=fr&google_domain=google.fr
```

**Turkish locale:**
```
/plugin/google/maps/search?token=TOKEN&q=kebap+istanbul&hl=tr&gl=tr&google_domain=google.com.tr
```

**Page 3:**
```
/plugin/google/maps/search?token=TOKEN&q=pizza+new+york&start=40
```

---

## From Search Results to More Data

Each `local_results[]` entry contains identifiers you can pass to the companion endpoints:

- **`place_id` or `data_cid`** → pass to [`/plugin/google/maps/place`](/documentation/google-scraper-api/maps/place) for enriched place details (menu, popular times, user reviews, images, summary).
- **`data_id` or `place_id`** → pass to [`/plugin/google/maps/reviews`](/documentation/google-scraper-api/maps/reviews) for paginated user reviews with ratings, owner responses, and guided review details.

---