> ## Documentation Index
> Fetch the complete documentation index at: https://clair.im/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Maps API

> Google Maps API: local businesses for a Maps query with place_id, coordinates, phone, website, and ratings, then one place with hours, rating histogram, and top reviews.

Two endpoints, one subscription. Both load Google Maps in a real browser, in
English. Google gives logged-out visitors either a **full**
or a **limited** view of Maps, and the API cannot pick which. The limited view
leaves out review counts, the rating histogram, review topics, reviews, and
most of the week's hours. Those fields are then null or empty; everything else
is the same.

See the [product page](https://clair.im/apis/google-maps).

## Search

`GET /v1/search?engine=google_maps` · **1 request**

One call scrolls the Maps results list and returns every place it loaded,
usually 20 to 70, repeats removed. There is no paging.

```sh theme={null}
curl -G https://api.clair.im/v1/search \
  -H "Authorization: Bearer YOUR_KEY" \
  --data-urlencode "engine=google_maps" \
  --data-urlencode "q=plumbers in Denver"
```

| Parameter               | Required | Contract                                                          |
| ----------------------- | -------- | ----------------------------------------------------------------- |
| `engine`                | yes      | Must be `google_maps`.                                            |
| `q`                     | yes      | What and where, as typed into Maps: `coffee in Austin TX`.        |
| `country`               | no       | ISO 3166-1 alpha-2 country the search is made from. Default `us`. |
| `latitude`, `longitude` | no       | Center the map on this point. Send both or neither.               |
| `zoom`                  | no       | 3 to 21, with `latitude`. Default 14.                             |

Do not send `page`, `limit`, or `cursor`. `next_cursor` is always null.

Each result includes `position`, `title`, `place_id`, `data_id` (the Maps
feature id), `cid`, `latitude`, `longitude`, `rating`, `reviews_count`,
`category`, `price`, `address`, `open_state`, `phone`, `website`,
`description`, `wheelchair_accessible`, `action_links[]` (`label`, `url`: Book
online, Order online, and the like), `thumbnail`, `sponsored`, and `url`.

* `address` is the street line Maps shows on the card. Service-area
  businesses show none.
* Service businesses usually carry `phone` and `website` on the card.
  Restaurants and shops often do not; call Place for those.
* `reviews_count` is null on cards Google drew in its limited view. One list
  can mix both.
* `sponsored` places are Google ads. Their `website` is null because the card
  links through an ad redirect.

## Place

`GET /v1/place?engine=google_maps` · **1 request**

```sh theme={null}
curl -G https://api.clair.im/v1/place \
  -H "Authorization: Bearer YOUR_KEY" \
  --data-urlencode "engine=google_maps" \
  --data-urlencode "place_id=ChIJszGcvzV0bIcR3_6j5Gru8sM"
```

| Parameter  | Required | Contract                                                           |
| ---------- | -------- | ------------------------------------------------------------------ |
| `engine`   | yes      | Must be `google_maps`.                                             |
| `place_id` | yes      | Google place id, from a search result or any Google Places source. |
| `country`  | no       | ISO 3166-1 alpha-2 country the page is loaded from. Default `us`.  |

The body is `place`:

| Field                                         | Contract                                                                                                                                                             |
| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `view`                                        | `full` or `limited`. Check it before relying on the review fields.                                                                                                   |
| `title`, `category`, `price`                  | As Maps shows them.                                                                                                                                                  |
| `address`, `located_in`, `plus_code`          | Full street address, the building or mall it sits in, and its plus code.                                                                                             |
| `phone`, `phone_e164`, `website`              | Display phone, E.164 phone, and the business's own site.                                                                                                             |
| `latitude`, `longitude`, `data_id`, `cid`     | Location and Google's other ids for the place.                                                                                                                       |
| `rating`, `reviews_count`, `rating_histogram` | Average, total, and count per star `1` to `5`.                                                                                                                       |
| `hours[]`                                     | `{ day, hours }`, such as `{ "day": "Friday", "hours": "7 AM to 8 PM" }`. Seven days on the full view, usually today only on the limited view.                       |
| `attributes[]`                                | Labels such as `Identifies as women-owned`.                                                                                                                          |
| `review_topics[]`                             | `{ topic, mentions }` from Google's review summary.                                                                                                                  |
| `reviews[]`                                   | The few reviews Google shows first: `id`, `author`, `author_url`, `local_guide`, `author_reviews`, `rating`, `date_text`, `text`, `owner_response{text, date_text}`. |

An id Google Maps does not know is `404 not_found`.

Auth, plans, rate limits, and error codes: [Authentication](/docs/authentication).