---
title: "Mapbox"
description: "Use Mapbox for MainSDK geocoding - access token, main.yaml, geo.geocode(), location as a hint never for access, testing and swapping."
section: "integrations"
canonical: "https://mainsdk.dev/docs/integrations/mapbox"
updated: "2026-10-28"
---

# Mapbox

> Use Mapbox for MainSDK geocoding - access token, main.yaml, geo.geocode(), location as a hint never for access, testing and swapping.

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

Mapbox is a maps and location platform. Behind [`geo`](https://mainsdk.dev/docs/interfaces/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.

## Interfaces it serves

### Location (`geo`)

- Status: Building for 0.7 · ships as a beta API
- Driver: `mapbox` (Mapbox)
- Docs: https://mainsdk.dev/docs/interfaces/geo.md

```yaml
geo:
  driver: mapbox
```

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

## 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

```yaml title="main.yaml"
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

```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` 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](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), 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

```yaml title="main.yaml"
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`](https://mainsdk.dev/docs/interfaces/network) and [`policy`](https://mainsdk.dev/docs/interfaces/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](https://mainsdk.dev/docs/interfaces/geo)
- [Google Maps Platform](https://mainsdk.dev/docs/integrations/google-maps)
- [Swap a driver](https://mainsdk.dev/docs/guides/swap-a-driver)