Location

geo gives you a coarse place from the request, for defaults such as a currency, and turns a typed address into a point. The place is a hint and never decides access.

A place guessed from a network address is wrong for people on a VPN or roaming, so using it to allow or deny someone locks out real people and lets attackers in. MainSDK refuses it in policy, access and auth.require.

geo:
  driver: platform-headers
  edge: cloudfront
  key: secret:MAPBOX_TOKEN
  cache-ttl: 30d
  timeout: 2s

import { geo } from "mainsdk/geo";

const hint = geo.of(request);                      // a hint for defaults, never for access
const place = await geo.geocode(address);          // a Place, or null when the provider is down

import { describe, it } from "node:test";
import assert from "node:assert/strict";
import { createTestApp, localGeoDriver } from "@mainsdk/testing";
import { geo } from "mainsdk/geo";

describe("geo", () => {
  it("geo AC4 geocodes from the table", async () => {
    const app = createTestApp({ yaml: "schema: 1\ngeo:\n  driver: local\n" });
    app.socialPorts.geo = localGeoDriver({
      "1 main st, springfield": { lat: 39.78, lon: -89.65, precision: "address", country: "US" },
    });
    assert.equal((await geo.geocode("1 Main St, Springfield"))?.country, "US");
    assert.equal(await geo.geocode("Nowhere Lane"), null);
  });
});

geo:
  driver: platform-headers

Quick start

schema: 1
deploy:
  target: vercel
geo:
  driver: platform-headers

import { geo } from "mainsdk/geo";

export async function GET(request: Request) {
  const hint = geo.of(request);   // { kind, source, country?, region?, city?, timezone? }
  return Response.json({ currency: hint.country === "IN" ? "INR" : "USD" });
}

geo.of() reads the headers of the one platform your app declares, here Vercel. It makes no call, never throws for a bad header, and returns an empty hint when the headers are missing.

Configuration

geo:
  driver: platform-headers      # platform-headers | mapbox | google-maps | local
  edge: cloudfront              # vercel | cloudflare | fly | cloudfront; defaults to deploy.target
  key: secret:MAPBOX_TOKEN      # mapbox and google-maps only
  cache-ttl: 30d                # 0 turns the cache off
  timeout: 2s                   # one geocode call; the answer is null after this

The headers each platform sets:

Cloudflare sends region, city and time zone only with its visitor location headers turned on. Fly sends no country header itself, so set x-mainsdk-country (and the others) from your own GeoIP step. Headers of every other platform are ignored, so a visitor cannot give your app a place by sending them.

Building it by hand

The SDK builds geo for you from main.yaml. Call these only when you wire it by hand, for example in a test or a custom runtime.

What you get

A GeoHint for defaults, and a Place for an address. The hint never holds an IP address, and each field is checked: the country is two letters (not XX or T1), the region a short code, the city cleaned and cut at 64 characters, the time zone an IANA name. A value that fails is left out.

type GeoHint = {
  readonly kind: "geo-hint";
  readonly source: "vercel" | "cloudflare" | "fly" | "cloudfront" | "none";
  readonly country?: string;    // ISO 3166-1 alpha-2, upper case
  readonly region?: string;
  readonly city?: string;
  readonly timezone?: string;   // IANA
};
type Place = {
  lat: number; lon: number;
  precision: "address" | "street" | "city" | "region" | "country";
  country?: string; region?: string; city?: string; label?: string;
};

An address is personal data. geo.geocode() sends it through network only to a provider host that serves the tenant's region, caches the place per tenant under a digest (never the address), and never writes the address to a log, an audit record, an error or a metric.

Examples

Geocode a delivery address

"use server";
import { geo } from "mainsdk/geo";

export async function placeFor(address: string) {
  const place = await geo.geocode(address, { country: "IN" });
  return place ?? { precision: "unknown" };   // null: not found, or the provider is down
}

geo.geocode() returns null when nothing matches and when the provider is down, so checkout keeps working with the typed address. It fails with MAIN-GEO-0003 for an empty address, one over 512 characters or a driver with no geocoder, and with MAIN-GEO-0004 when the driver has no host for the tenant's region.

Suggest a market in a Hono API

import { Hono } from "hono";
import { geo } from "mainsdk/geo";

const app = new Hono();

app.get("/suggested-market", (c) => {
  const { country } = geo.of(c.req.raw);
  return c.json({ suggested: country ?? null });
});

export default app;

The person still chooses. Market overlays resolve from the user's and organisation's context, not from the hint.

Errors and checks

See check codes and errors.

Swapping drivers

geo:
  driver: mapbox   # was platform-headers
  key: secret:MAPBOX_TOKEN

Your geo.of() and geo.geocode() calls stay the same. Each driver serves the regions it declares: Mapbox serves us, Google Maps Platform us and eu. For a tenant in another region the call fails with MAIN-GEO-0004 instead of sending the address. See Mapbox and Google Maps Platform.

Testing

createTestApp installs the local driver, which geocodes from a table with no network. Set geo.driver: local in your test settings, and give a test its own table:

import { describe, it } from "node:test";
import assert from "node:assert/strict";
import { createTestApp, localGeoDriver } from "@mainsdk/testing";
import { geo } from "mainsdk/geo";

describe("geo", () => {
  it("geo AC4 geocodes from the table", async () => {
    const app = createTestApp({ yaml: "schema: 1\ngeo:\n  driver: local\n" });
    app.socialPorts.geo = localGeoDriver({
      "1 main st, springfield": { lat: 39.78, lon: -89.65, precision: "address", country: "US" },
    });
    assert.equal((await geo.geocode("1 Main St, Springfield"))?.country, "US");
    assert.equal(await geo.geocode("Nowhere Lane"), null);
  });
});

fakeGeoProvider("mapbox") and fakeGeoProvider("google-maps") are fake provider servers for the real drivers: they answer in each provider's response shape, record every request and can be set to down, refused, garbage or hang to test the null path. Every driver, yours included, runs the geo@1 conformance suite with runDriverConformance(driver).

Security and privacy

• Location is a hint, never used for access. Passing a GeoHint into a policy, access or auth.require fails with MAIN-GEO-0001, and mainsdk check flags geo.of in access code. The guard cannot follow a country you copy into a plain string, so do not.
• The hint never holds an IP address, and geo.of() reads only the declared platform's headers.
• Addresses you geocode are personal data: sent only to a host that serves the tenant's region, cached under a digest, never logged. Label the fields that store them in db.
• Precise location needs consent. geo handles a coarse place and typed addresses, not a device's coordinates.

FAQ

Can I block a country with geo? No. Use protect policy for country rules on protected files, and network and policy for rules you enforce.

Does geo choose the user's language? No. The locale comes from the user's choice first; see Languages and formats.

How do I count where my app is used? With analytics: analytics.query({ by: ["country"] }).

Why is my hint empty? No platform is declared (deploy.target or geo.edge), or the platform did not send the header. mainsdk check reports the first.

Next

• Use location in your app
• Languages and formats
• Where the app is used
• Policy decisions