Google Maps Platform

Google Maps Platform is Google's set of maps, places and location APIs. Behind 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.

geo:
  driver: google-maps

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

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

"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 for the full contract.

Limits and notes

• Spec 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.
• Precise location needs consent.
• Google's terms limit how you cache and display results; check them before storing output.

Swap to or from it

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
• Mapbox
• Swap a driver