---
title: "Google Maps Platform"
description: "Use Google Maps Platform for MainSDK geocoding - API key, main.yaml, geo.geocode(), location as a hint never for access, testing and swapping."
section: "integrations"
canonical: "https://mainsdk.dev/docs/integrations/google-maps"
updated: "2026-10-28"
---

# Google Maps Platform

> Use Google Maps Platform for MainSDK geocoding - API key, main.yaml, geo.geocode(), location as a hint never for access, testing and swapping.

Canonical: https://mainsdk.dev/docs/integrations/google-maps · Updated: 2026-10-28

Google Maps Platform is Google's set of maps, places and location APIs. Behind [`geo`](https://mainsdk.dev/docs/interfaces/geo), its geocoding turns addresses into places with `geo.geocode()`, for example to check a delivery address. Pick it when you already use Google Maps in your app, or need its address coverage in your markets. Location from `geo` is always a hint for defaults, never an input to access decisions.

## Interfaces it serves

### Location (`geo`)

- Status: Building for 0.7 · ships as a beta API
- Driver: `google-maps` (Google Maps Platform)
- Docs: https://mainsdk.dev/docs/interfaces/geo.md

```yaml
geo:
  driver: google-maps
```

Swap to another provider: `platform-headers`, `mapbox`, `local`.

## Before you start

1. **Create a Google Cloud project** and attach a billing account; Google Maps Platform requires one.
2. **Enable the Geocoding API** in that project.
3. **Create an API key** for server-side use and restrict it to the Geocoding API. Keep it separate from any browser key you use to show maps.
4. **Read the service terms** on caching and storing results before you keep geocoding output.
5. **Store the key** in your secrets manager, never in code or a committed env file.

## Configure

```yaml title="main.yaml"
geo:
  driver: google-maps
  key: secret:GOOGLE_MAPS_API_KEY
```

The hint always comes from your platform's headers; this driver adds geocoding. Google Maps Platform serves the regions `us` and `eu` here: for a tenant in another region `geo.geocode()` fails with `MAIN-GEO-0004` before the address is sent. The request shape follows the provider's public documentation, so send one address through your account before the first live use and confirm the regional host with the provider.

## Use it

```ts title="app/checkout/actions.ts"
"use server";
import { auth } from "mainsdk";
import { geo } from "mainsdk/geo";

export async function placeFor(req: Request, address: string) {
  await auth.require(req);
  return geo.geocode(address);   // a Place ({ lat, lon, precision, country?, region?, city?, label? }), or null
}
```

Use the result to fill in a form or suggest a store. The user still confirms.

## Local development and testing

- **Tests:** `createTestApp()` from `@mainsdk/testing` runs `geo` on an in-memory fake, so tests make no billable calls. Set `geo.driver: local` for a table, or use `fakeGeoProvider("google-maps")` from `@mainsdk/testing` to run this driver against a fake server.
- **Outages:** `chaos.on("geo", { outage: true })` simulates Google Maps Platform being down.
- **Development:** use a separate, restricted key and a quota in your Google Cloud project, so a bug in development cannot run up usage.

## What MainSDK adds on top

- Location is a hint, never used for access. Market overlays resolve from the user's and organisation's context, not from location.
- The same `geo.of()` and `geo.geocode()` calls work with every listed driver.
- The key resolves from a `secret:` reference and is redacted from logs.

See [Location](https://mainsdk.dev/docs/interfaces/geo) for the full contract.

## Limits and notes

- Spec [geo](https://mainsdk.dev/docs/interfaces/geo), milestone 0.7. Results are cached per tenant for `geo.cache-ttl` (30 days by default); check the provider's terms before you keep them longer.
- Addresses you geocode are personal data. Label the fields that store them in [`db`](https://mainsdk.dev/docs/interfaces/db).
- Precise location needs consent.
- Google's terms limit how you cache and display results; check them before storing output.

## Swap to or from it

```yaml title="main.yaml"
geo:
  driver: google-maps   # was mapbox
```

Your calls stay the same. Results you stored stay as they are; check the old provider's terms on keeping them.

## FAQ

**Why restrict the API key?** An unrestricted key can call any enabled Google API and bill your account if it leaks. Restrict it to the Geocoding API.

**Can I use `geo` to decide which market a user is in?** No. It can suggest one; the user chooses, and overlays resolve from the user's and organisation's context.

## Next

- [Location](https://mainsdk.dev/docs/interfaces/geo)
- [Mapbox](https://mainsdk.dev/docs/integrations/mapbox)
- [Swap a driver](https://mainsdk.dev/docs/guides/swap-a-driver)