# Google Maps: Search places

`google_maps/places/search` · version 1.3.0 · pilot · 20 credits a call

One page of places for a Google Maps search, 20 at most, as the results list shows them.

Categories: Lead generation

## When to use

You need the places Google Maps lists for a search such as "dentist" near a point or "restaurants in Lyon": name, categories, address, coordinates, phone, website, rating, opening hours. For one place's full profile, use google_maps/places/get; for its reviews, google_maps/reviews/list.

## Call

```bash
curl https://api.lobstr.io/v2/run \
  -H "Authorization: Bearer $LOBSTR_API_KEY" \
  -H "content-type: application/json" \
  -d '{"source": "google_maps", "operation": "places/search", "options": {"query": "restaurants in Lyon", "page": 1}}'
```

The answer's `next` is the whole call for the following page: send it as it is. `null` on the last page.

Beside `options`, the call takes:

| Parameter | Type | Description |
|---|---|---|
| `fields` | array of string | The record fields to keep, by path (`title`, `address.city`); `object`, `id` and `position` always come. Left out: every field. |
| `limit` | integer | Only the first N records of this call (1 to 1000), in the call's order; the call costs the same, and `next` keeps the limit. Left out: every record. |

## Options

| Option | Type | Required | Default | Description |
|---|---|---|---|---|
| `query` | string | yes |  | What you would type in Google Maps' search box: a kind of place ("dentist"), a name, or both with a place ("restaurants in Lyon"). Results are ranked for `country` (default us) and written in `language` (default en): set them for a search elsewhere. |
| `near` | object |  |  | Optional: the point to search around, as the map would centre on it ("bakery" around a spot). Leave it out when the query names its place ("restaurants in Lyon", "Le Vieux Lyon, Lyon"): Google locates it, better than a guessed point. Left out with a query naming no place, Google uses the country. |
| `zoom` | integer, 3 to 20 |  | `14` | The map's zoom around `near`, from 3 (a continent) to 20 (a street). Google lists places from the whole area the map shows, ranked by relevance, not by distance: at 13 they spread about 4 km around `near`, at 15 about 1 km (a neighbourhood), at 17 a few hundred metres (a street). Used only with `near`. |
| `language` | string |  | `"en"` | The language of names, categories and hours, as an ISO 639-1 code. |
| `country` | string |  | `"us"` | The country Google ranks results for, as an ISO 3166-1 alpha-2 code in lower case. |
| `page` | integer, 1 to 20 |  | `1` | The page to start at; `next` in an answer goes on from it with `cursor`. Google Maps stops listing after 200 to 300 places, depending on the search: the last page is short, a page past the end is empty and free. |
| `cursor` | string |  |  | Where to go on, from `next` in an answer, as it is: opaque, and only for the search it was given with (otherwise `invalid_cursor`). Leave it out to start at `page`. |

## Record

Each item of `results`. Every field is always present, `null` when the site gives nothing.

| Field | Type | Description |
|---|---|---|
| `object` | `"place"` | The kind of record: a place, whichever site it comes from. |
| `id` | string | Google's place id (ChIJ...), stable across languages; repeated in ids.place_id. |
| `position` | integer | Its rank among the places of the search, across pages: 21 is the first of page 2. |
| `name` | string |  |
| `categories` | array of string | As Google Maps names them, the main one first. |
| `primary_category_id` | string | null | Null in a list of results: Google gives a place's category id only on its page (google_maps/places/get). result_type is the family a list does give. |
| `result_type` | string | null | Google's search-result type for the place, the same in every language: a family for most places (shopping, industrial, personal_care), finer for some (french_restaurant, bakery, park). Not its category: categories has those by name, and places/get gives primary_category_id. |
| `address` | object |  |
| `address.full` | string | null |  |
| `address.street` | string | null |  |
| `address.neighborhood` | string | null | The district Google files the place under: Manhattan. |
| `address.city` | string | null |  |
| `address.postal_code` | string | null |  |
| `address.state` | string | null | The state or region, where the address has one: New York. |
| `address.country_code` | string | null | ISO 3166-1 alpha-2 |
| `location` | object |  |
| `location.latitude` | number | Degrees, 7 decimals (about a centimetre). |
| `location.longitude` | number | Degrees, 7 decimals. |
| `phone` | string | null | E.164; null when Google gives no international number. |
| `website_url` | string | null (uri) |  |
| `rating` | object | null | The average rating and how many reviews make it; null when the place has none. |
| `rating.value` | number |  |
| `rating.scale` | `5` | The best possible value: ratings from other sites compare once divided by it. |
| `rating.count` | integer | null |  |
| `rating.distribution` | object | null | How many reviews give each number of stars, 1 to 5; they add up to count. Null when Google does not say. A list of results seldom has it; a search naming one place does. |
| `rating.distribution.1` | integer |  |
| `rating.distribution.2` | integer |  |
| `rating.distribution.3` | integer |  |
| `rating.distribution.4` | integer |  |
| `rating.distribution.5` | integer |  |
| `review_topics` | array | null | The topics Google draws from the reviews (pleasant waiters), how many reviews mention each, and the id Google filters the reviews by; null when the answer has none (a list of results). |
| `review_topics[].name` | string |  |
| `review_topics[].mentions` | integer | null |  |
| `review_topics[].id` | string | null |  |
| `description` | string | null | Google's short summary of the place, when it has one. |
| `owner_description` | string | null | What the place says of itself on its profile, as its owner wrote it (From the owner); null when it says nothing. |
| `booking_url` | string | null (uri) |  |
| `hours` | array | null | The week, Monday first, in local time (`timezone`). A day closed has no interval; `intervals: null` is a day Google gives in a shape we cannot read (unknown, never closed); a close earlier than its open ends the next day; null when Google shows no hours. |
| `hours[].day` | `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday` |  |
| `hours[].intervals` | array | null |  |
| `hours[].intervals[].open` | string | HH:MM, local time. |
| `hours[].intervals[].close` | string | HH:MM, local time; 24:00 is midnight. |
| `more_hours` | array | Hours of a service apart from the place's own (Kitchen, Brunch, Takeout...), labelled in `language`. |
| `more_hours[].label` | string |  |
| `more_hours[].hours` | array | null | The week, Monday first, in local time (`timezone`). A day closed has no interval; `intervals: null` is a day Google gives in a shape we cannot read (unknown, never closed); a close earlier than its open ends the next day; null when Google shows no hours. |
| `more_hours[].hours[].day` | `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday` |  |
| `more_hours[].hours[].intervals` | array | null |  |
| `more_hours[].hours[].intervals[].open` | string | HH:MM, local time. |
| `more_hours[].hours[].intervals[].close` | string | HH:MM, local time; 24:00 is midnight. |
| `timezone` | string | null | IANA time zone. |
| `attributes` | array | What Google lists about the place in its results (accessibility...). `id` is Google's own, the same in every language; `value` is true when the place has it. |
| `attributes[].id` | string |  |
| `attributes[].label` | string | null |  |
| `attributes[].group` | string |  |
| `attributes[].value` | boolean | null | true when Google shows the place has it; null for anything else it says. |
| `highlights` | array | Google's badges on the place: LGBTQ+ friendly, women-owned. `id` is the same in every language. |
| `highlights[].id` | string | null |  |
| `highlights[].label` | string |  |
| `actions` | array | What people can do from Google: reserve a table, order online. `url` is Google's own page for it; `providers` are the services it sends to (OpenTable, a delivery service, the place's site). |
| `actions[].type` | `reserve`, `order`, null | null for a kind of action we do not name yet; `label` says it. |
| `actions[].label` | string |  |
| `actions[].url` | string | null (uri) |  |
| `actions[].providers` | array |  |
| `actions[].providers[].name` | string |  |
| `actions[].providers[].domain` | string |  |
| `actions[].providers[].url` | string | null (uri) |  |
| `owner` | object | null | The Google account that manages the place's profile, as Google shows it. |
| `owner.id` | string |  |
| `owner.name` | string |  |
| `popular_times` | object | null | Google's "Popular times": for each day, how busy each hour usually is, 0 (empty) to 100 (busiest); and how busy it is now when Google says so (`live`, its label in `language`). null when Google shows none. |
| `popular_times.week` | array |  |
| `popular_times.week[].day` | `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday` |  |
| `popular_times.week[].hours` | array |  |
| `popular_times.week[].hours[].hour` | integer, 0 to 23 |  |
| `popular_times.week[].hours[].busyness` | integer, 0 to 100 |  |
| `popular_times.live` | object | null |  |
| `popular_times.live.hour` | integer | null |  |
| `popular_times.live.busyness` | integer, 0 to 100 |  |
| `popular_times.live.label` | string | null |  |
| `admission` | object | null | What a visit costs, for a place one visits (a museum, a monument): the price Google shows, the official site, the sellers. |
| `admission.price` | object | null | A price: `amount` and `currency` (ISO 4217) when they read, null otherwise ("$" names several currencies); `text` as Google wrote it. |
| `admission.price.amount` | number | null |  |
| `admission.price.currency` | string | null |  |
| `admission.price.text` | string |  |
| `admission.url` | string | null (uri) |  |
| `admission.domain` | string | null |  |
| `admission.offers` | array |  |
| `admission.offers[].seller` | string | null |  |
| `admission.offers[].url` | string | null (uri) |  |
| `admission.offers[].price` | object | null | A price: `amount` and `currency` (ISO 4217) when they read, null otherwise ("$" names several currencies); `text` as Google wrote it. |
| `admission.offers[].price.amount` | number | null |  |
| `admission.offers[].price.currency` | string | null |  |
| `admission.offers[].price.text` | string |  |
| `hotel` | object | null | For a hotel: the night Google prices, its price for that night, and the hotels Google compares it with. |
| `hotel.check_in` | string | null (date) |  |
| `hotel.check_out` | string | null (date) |  |
| `hotel.price` | object | null | A price: `amount` and `currency` (ISO 4217) when they read, null otherwise ("$" names several currencies); `text` as Google wrote it. |
| `hotel.price.amount` | number | null |  |
| `hotel.price.currency` | string | null |  |
| `hotel.price.text` | string |  |
| `hotel.similar` | array |  |
| `hotel.similar[].name` | string |  |
| `hotel.similar[].feature_id` | string | null |  |
| `hotel.similar[].price` | object | null | A price: `amount` and `currency` (ISO 4217) when they read, null otherwise ("$" names several currencies); `text` as Google wrote it. |
| `hotel.similar[].price.amount` | number | null |  |
| `hotel.similar[].price.currency` | string | null |  |
| `hotel.similar[].price.text` | string |  |
| `hotel.similar[].rating` | object | null |  |
| `hotel.similar[].rating.value` | number |  |
| `hotel.similar[].rating.scale` | `5` |  |
| `hotel.similar[].rating.count` | integer | null |  |
| `hotel.similar[].note` | string | null | What Google says the price includes: breakfast, parking. |
| `things_to_do` | array | The tours and activities Google offers at the place: title, seller, price, duration, rating. |
| `things_to_do[].title` | string |  |
| `things_to_do[].url` | string | null (uri) |  |
| `things_to_do[].seller` | string | null |  |
| `things_to_do[].price` | object | null | A price: `amount` and `currency` (ISO 4217) when they read, null otherwise ("$" names several currencies); `text` as Google wrote it. |
| `things_to_do[].price.amount` | number | null |  |
| `things_to_do[].price.currency` | string | null |  |
| `things_to_do[].price.text` | string |  |
| `things_to_do[].duration` | string | null | As Google writes it |
| `things_to_do[].rating` | object | null |  |
| `things_to_do[].rating.value` | number |  |
| `things_to_do[].rating.scale` | `5` |  |
| `things_to_do[].rating.count` | integer | null |  |
| `ids` | object | Every id Google gives the place: the one another call or another tool may need. |
| `ids.place_id` | string |  |
| `ids.cid` | string | null | Customer id: the second half of feature_id, in decimal; google.com/maps?cid=<cid> opens the place. |
| `ids.feature_id` | string | null | Feature id (0x...:0x...), what reviews and photos are listed by. |
| `ids.kgmid` | string | null | Knowledge Graph id (/g/...). |
| `photo_url` | string | null (uri) | The place's main photo. |
| `url` | string (uri) | The place on Google Maps (Maps URLs, query_place_id). |
| `source_url` | string (uri) | The search these values were read from. |
| `observed_at` | string (date-time) | When they were read |

Example:

```json
{
  "object": "place",
  "id": "ChIJAAAAAAAAAAAAAAAAAAAAAAA",
  "position": 1,
  "name": "Acme Bistro",
  "categories": [
    "French restaurant"
  ],
  "primary_category_id": null,
  "result_type": "french_restaurant",
  "address": {
    "full": "1 Rue Exemple, 69005 Lyon, France",
    "street": "1 Rue Exemple",
    "neighborhood": null,
    "city": "Lyon",
    "postal_code": "69005",
    "state": null,
    "country_code": "FR"
  },
  "location": {
    "latitude": 45.7623,
    "longitude": 4.8275
  },
  "phone": "+33400000000",
  "website_url": "https://acme-bistro.example",
  "rating": {
    "value": 4.5,
    "scale": 5,
    "count": 1280,
    "distribution": null
  },
  "review_topics": null,
  "description": "Local food and wine in vintage surrounds",
  "owner_description": null,
  "booking_url": "https://acme-bistro.example/booking",
  "hours": [
    {
      "day": "monday",
      "intervals": [
        {
          "open": "11:30",
          "close": "14:30"
        },
        {
          "open": "18:30",
          "close": "22:00"
        }
      ]
    },
    {
      "day": "tuesday",
      "intervals": []
    }
  ],
  "more_hours": [
    {
      "label": "Kitchen",
      "hours": [
        {
          "day": "monday",
          "intervals": [
            {
              "open": "12:00",
              "close": "14:00"
            }
          ]
        }
      ]
    }
  ],
  "timezone": "Europe/Paris",
  "attributes": [
    {
      "id": "has_wheelchair_accessible_entrance",
      "label": "Wheelchair-accessible entrance",
      "group": "accessibility",
      "value": true
    }
  ],
  "highlights": [
    {
      "id": "lgbtq_friendly",
      "label": "LGBTQ+ friendly"
    }
  ],
  "actions": [
    {
      "type": "reserve",
      "label": "Reserve a table",
      "url": "https://www.google.com/maps/reserve/v/dine/c/AAAAAAAAAAA?source=pa&hl=en",
      "providers": [
        {
          "name": "Acme Bookings",
          "domain": "acme-bookings.example",
          "url": "https://acme-bookings.example/r/1"
        }
      ]
    }
  ],
  "owner": {
    "id": "100000000000000000000",
    "name": "Acme Bistro (Owner)"
  },
  "popular_times": {
    "week": [
      {
        "day": "monday",
        "hours": [
          {
            "hour": 12,
            "busyness": 45
          },
          {
            "hour": 13,
            "busyness": 80
          }
        ]
      }
    ],
    "live": {
      "hour": 13,
      "busyness": 60,
      "label": "Usually not too busy"
    }
  },
  "admission": null,
  "hotel": null,
  "things_to_do": [],
  "ids": {
    "place_id": "ChIJAAAAAAAAAAAAAAAAAAAAAAA",
    "cid": "1000000000000000000",
    "feature_id": "0x47f4000000000000:0x0de0b6b3a7640000",
    "kgmid": "/g/11aaaaaaaa"
  },
  "photo_url": "https://lh3.googleusercontent.com/example.jpg",
  "url": "https://www.google.com/maps/search/?api=1&query=45.7623%2C4.8275&query_place_id=ChIJAAAAAAAAAAAAAAAAAAAAAAA",
  "source_url": "https://www.google.com/maps/search/restaurants+in+Lyon",
  "observed_at": "2026-10-26T09:00:00Z"
}
```

## Price

20 credits a call, whatever the page holds: a short last page costs a whole call. An empty page (past the end, or no results) and a failed call are free.

## Errors

| Code | Status | Retry | Message |
|---|---|---|---|
| `site_unavailable` | 503 | yes | Google Maps did not answer in time or refused the call; retry later (not charged). |
| `unexpected_answer` | 424 | no | Google Maps answered in a shape we do not read yet; we are told and fix it, and it is not charged. Retrying now gives the same. |
| `missing_api_key` | 401 | no | No API key: send it as `Authorization: Bearer <key>`. |
| `invalid_api_key` | 401 | no | The key is not valid, or not anymore. |
| `insufficient_credits` | 402 | no | The call costs more credits than are left. |
| `unknown_operation` | 404 | no | No such source and operation in the catalog. |
| `timeout` | 408 | yes | The call did not finish within its deadline (not charged). |
| `invalid_body` | 422 | no | The body is not a call: source, operation, options. |
| `invalid_options` | 422 | no | An option is missing or out of its contract; `param` names it. |
| `invalid_idempotency_key` | 400 | no | The Idempotency-Key header is not printable ASCII, or too long. |
| `concurrency_limit` | 429 | yes | The plan's calls at a time are all in progress (Free 1, Starter 2, Pro 10, Team 50); retry when one has finished (not charged, never queued). |
| `service_busy` | 503 | yes | Too many calls at once on the account; retry in a few seconds. |
| `balance_unavailable` | 503 | yes | The balance could not be read; retry in a few seconds. |

## Changelog

- **1.3.0** (2026-11-13): `next` keeps the search as it was written and goes on with `cursor`, opaque, as every paged operation of the API (Google's page tokens): copy `next` as before. `page` still starts at any page.
- **1.2.0** (2026-10-27): primary_category_id said it was the main category's id but held Google's search-result type, a family for most places (shopping for a sewing machine store). That value is now result_type. primary_category_id is the main category's real id, which only a place's page gives: places/get fills it, places/search leaves it null.
- **1.1.0** (2026-10-27): Three fields Google gives on a place's page: rating.distribution (reviews per number of stars), review_topics (the topics drawn from the reviews, with their mentions) and owner_description (what the place says of itself). Found by the preventive loop (lobstrio/platform#19).
- **1.0.0** (2026-10-26): First version on the API v2.

Schema: https://api.lobstr.io/v2/catalog/google_maps/places/search · All operations: https://api.lobstr.io/v2/catalog.md
