# Google Maps

`POST https://api.serpkite.com/v1/maps` · Credits: 1 per page

Local businesses with place_id, rating, review count, coordinates, hours, phone and website.

Google Maps search: businesses and points of interest with coordinates, rating, review count, hours, phone, website and the IDs you need for [/v1/reviews](https://serpkite.com/docs/endpoints/reviews).

Pass `location` for a city-level search, or `ll` for an exact viewport.

## Request body

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `q` **required** | string |  | The search query. Required. Up to 2,048 characters. |
| `country` | string | `us` | Country to search from, as a two-letter ISO code (us, gb, de, in…). |
| `language` | string | `en` | Interface language, as a language code (en, de, fr, pt-BR…). |
| `location` | string |  | Canonical location for local results, e.g. "Austin, Texas, United States". Overrides country for geo. |
| `uule` | string |  | Google-encoded location string. Use instead of location if you already have it. |
| `ll` | string |  | Maps only: viewport as "@lat,lng,zoom", e.g. "@52.52,13.40,14z". |
| `page` | integer | `1` | Results page, 1–10. Each page is billed separately. |
| `format` | string | `json` | Response format. markdown is LLM-ready prose; compact is JSON with only the fields agents need. One of: `json`, `compact`, `markdown`. |
| `fields` | string |  | Comma-separated projection, e.g. results.title,results.link,knowledge_graph. Cuts tokens. |
| `max_age` | integer |  | Accept a cached result up to this many seconds old. Cache hits cost 50% of the credits. |

## Example request

cURL:

```bash
curl https://api.serpkite.com/v1/maps \
  -H "Authorization: Bearer $SERPKITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q":"coffee roasters","location":"Berlin, Germany"}'
```

TypeScript:

```ts
import { SerpKite } from "serpkite";

const sk = new SerpKite(); // reads SERPKITE_API_KEY
const res = await sk.maps({ q: "coffee roasters", location: "Berlin, Germany" });
console.log(res.results[0].title, res.meta.credits_used);
```

Python:

```python
from serpkite import SerpKite

sk = SerpKite()  # reads SERPKITE_API_KEY
res = sk.maps("coffee roasters", location="Berlin, Germany")
print(res.results[0].title, res.meta.credits_used)
```

## Response fields

| Field | Type | Description |
| --- | --- | --- |
| `request` | object | The normalised request, with defaults filled in: `endpoint`, `engine`, `q`, `country`, `language`, `location`, `num`, `page`, `device`, `autocorrect`… |
| `results[]` | array | `position`, `title`, `address`, `latitude`, `longitude`, `rating`, `rating_count`, `price_level`, `type`, `types[]`, `website`, `phone_number`, `opening_hours`, `thumbnail_url`, `place_id`, `cid`, `fid`. |
| `meta` | object | `request_id`, `credits_used`, `cached`, `cached_at`, `engine` (the provider that answered), `route` (provider attempts, see [Search providers](https://serpkite.com/docs/providers)), `latency_ms`, `parse_quality` (`ok`, `partial`, `empty`), `resolved_urls`. |

## Example response

```json
{
  "request": {
    "endpoint": "maps",
    "engine": "google",
    "q": "coffee roasters",
    "location": "Berlin, Germany",
    "language": "en"
  },
  "results": [
    {
      "position": 1,
      "title": "Example Coffee Roasters",
      "address": "Beispielstraße 1, 10115 Berlin",
      "latitude": 52.5321,
      "longitude": 13.3849,
      "rating": 4.7,
      "rating_count": 812,
      "price_level": "€€",
      "type": "Coffee roasters",
      "types": [
        "Coffee roasters",
        "Cafe"
      ],
      "website": "https://coffee.example.de",
      "phone_number": "+49 30 0000000",
      "opening_hours": {
        "Monday": "8 AM–6 PM",
        "Sunday": "10 AM–5 PM"
      },
      "place_id": "ChIJexample0000000000000",
      "cid": "1234567890123456789"
    }
  ],
  "meta": {
    "request_id": "req_01J8ZK4M6Q2V7",
    "credits_used": 1,
    "cached": false,
    "engine": "google",
    "latency_ms": 1034,
    "parse_quality": "ok",
    "resolved_urls": true
  }
}
```

## Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `invalid_request` | A parameter is missing or invalid. |
| 401 | `unauthorized` | The API key is missing, invalid or revoked. |
| 402 | `insufficient_credits` | Your balance is too low. Buy a pack or wait for the monthly free grant. |
| 429 | `rate_limited` | Too many requests per second for your plan. Retry after the Retry-After header. |
| 503 | `upstream_error` | Google could not be fetched or parsed. Not billed; retry after Retry-After. |

All errors: https://serpkite.com/docs/errors

## Notes

- Use `place_id`, `cid` or `fid` from a result to fetch its reviews.

## Related

- [Places](https://serpkite.com/docs/endpoints/places)
- [Reviews](https://serpkite.com/docs/endpoints/reviews)
- [Localization](https://serpkite.com/docs/localization)