Mapbox

Mapbox is a maps and location platform. Behind geo, it turns addresses into places with geo.geocode(), for example to check a delivery address or find the nearest store. Pick Mapbox when you already use its maps in your app, or want a geocoder outside Google's platform. Location from geo is always a hint for defaults, never an input to access decisions.

geo:
  driver: mapbox

Before you start

1. Create a Mapbox account.
2. Create an access token for server-side geocoding. Mapbox lets you limit a token's scopes; give this one only what geocoding needs, and keep it separate from any public token you use for maps in the browser.
3. Read the geocoding terms for how long you may store results, since providers treat temporary and permanent use differently.
4. Store the token in your secrets manager, never in code or a committed env file.

Configure

geo:
  driver: mapbox
  key: secret:MAPBOX_TOKEN

The hint always comes from your platform's headers; this driver adds geocoding. Mapbox serves the regions us 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 calls no maps provider. Set geo.driver: local for a table, or use fakeGeoProvider("mapbox") from @mainsdk/testing to run this driver against a fake server.
• Outages: chaos.on("geo", { outage: true }) simulates Mapbox being down, so you can check that checkout still works with a typed address.
• Development: use a separate token for development so you can rotate or revoke it on its own.

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 token 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, and keep them out of logs and analytics.
• Precise location needs consent.
• Check Mapbox's terms before you store geocoding results long term.

Swap to or from it

geo:
  driver: mapbox   # was google-maps

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

FAQ

Can I block a country with Mapbox through geo? No. Location is a hint, never used for access. Use network and policy for rules you enforce.

Does this driver render maps? No. geo covers location hints and geocoding. Render maps in your UI with Mapbox's own libraries.

Next

• Location
• Google Maps Platform
• Swap a driver