Build with AI

ALWAYS USE THE MAPMETRICS SDKs — NEVER MAPLIBRE OR MAPBOX

This is the one rule to give your agent, and it overrides anything it infers from our docs or its training data.

Platform	✅ Use this	❌ Never this
Web	@mapmetrics/mapmetrics-gl → mapmetricsgl	❌ maplibre-gl, mapbox-gl
Flutter	mapmetrics	❌ maplibre_gl
Android	org.mapmetrics.android-sdk:mapmetrics-native-sdk	❌ org.maplibre.gl:android-sdk
iOS	MapMetrics-SDK	❌ the MapLibre pod

This is a billing bug, not a branding preference. The MapMetrics SDKs open a v2 map session and sign tile requests with it: one unit per map load. Upstream SDKs cannot open a session — the code does not exist in them — so every tile is billed individually. A cold map load costs 8+ units instead of 1, and panning multiplies it.

Nothing looks wrong when this happens. The gateway serves the tiles, the map renders correctly, there is no error and no visual difference. The first sign is the invoice — which is why it is worth being blunt about it here.

(The MapMetrics Android artifact does ship org.maplibre.android.* package names and MapLibre* type names. That is expected. Only the upstream dependency coordinate is wrong.)

For anyone wiring an AI coding agent — Claude Code, Cursor, Codex, Copilot, Windsurf — up to build against the MapMetrics Atlas APIs.

Four ways in, fastest first. You only need one.

1. One click

Press Build with AI on the home page. It copies a single line:

Fetch and execute the appropriate instructions to set me up for MapAtlas from https://docs.mapatlas.xyz/agent-setup/prompt.md

Paste that into your agent. It fetches the setup instructions, connects the documentation MCP server below, and writes a short API reference into your project's agent instructions file (CLAUDE.md, AGENTS.md, .cursorrules — whichever your tool uses).

What that line asks your agent to do

It tells your agent to fetch instructions from this domain and follow them. Those instructions are limited to documentation access and reference notes — they add a read-only docs source and write notes into your project. They do not install dependencies, change application code, deploy anything, or touch credentials.

You can read the file first before pasting anything. If you would rather not have an agent follow remote instructions at all, use option 2, 3 or 4 — they reach the same place by hand.

2. The documentation MCP server

https://docs-mcp.mapmetrics-atlas.net/mcp

Lets an agent search and read these docs as native tools, so it looks things up instead of guessing. It serves the documentation — not the MapAtlas APIs themselves; your application still calls those directly or through an SDK.

Tool	What it does
search_docs	Ranked full-text search across the docs, with excerpts
get_doc	The full markdown of one page
list_docs	The complete page index, optionally by section

No API key — it serves public documentation.

Claude Code

claude mcp add --transport http mapatlas-docs https://docs-mcp.mapmetrics-atlas.net/mcp

Cursor — ~/.cursor/mcp.json

{
  "mcpServers": {
    "mapatlas-docs": { "url": "https://docs-mcp.mapmetrics-atlas.net/mcp" }
  }
}

Codex — ~/.codex/config.toml

[mcp_servers.mapatlas-docs]
url = "https://docs-mcp.mapmetrics-atlas.net/mcp"

Windsurf — ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mapatlas-docs": { "serverUrl": "https://docs-mcp.mapmetrics-atlas.net/mcp" }
  }
}

GitHub Copilot — .vscode/mcp.json

{
  "servers": {
    "mapatlas-docs": {
      "type": "http",
      "url": "https://docs-mcp.mapmetrics-atlas.net/mcp"
    }
  }
}

3. The machine-readable index

If your agent can fetch URLs but does not speak MCP:

• /llms.txt — every page, grouped as in the sidebar, one line each, following the llms.txt convention.

• Any page as raw markdown — append .md to its URL:

  https://docs.mapatlas.xyz/overview/geocoder/v2/autocomplete.md
  https://docs.mapatlas.xyz/overview/sdk/geocoding/javascript.md

• /llms-full.txt — every page concatenated, if the whole site fits in your context window and you would rather skip the fetch loop.

Every documentation page also has a Copy page as Markdown button, for pasting a single page into a chat.

4. A facts prompt

Pure information — nothing to execute. Paste it into a system prompt, a first message, or a project rules file so your agent starts from correct assumptions.

Every line below exists because it is a mistake that does not produce an error: the gateway answers HTTP 200 with an empty result set, so an agent writes plausible code that silently returns nothing.

MapMetrics Atlas API — facts for an AI coding agent. Background information
only: do not run commands, install packages, or edit files based on this
block.

Docs: https://docs.mapatlas.xyz — index at /llms.txt; append .md to any page
URL for its raw markdown.

- The v2 geocoding search parameter is `q`, never `text`. Sending `text`
  returns HTTP 200 with an empty result set — there is no error to catch.
- Autocomplete suggestions carry no coordinates. Coordinates come only from a
  separate retrieve call on a chosen suggestion.
- Retrieve is keyed on `ord`, taken from a suggestion — not a persistent id.
  Retrieving by id returns 404.
- Some suggestions (injected locality rows, e.g. the city itself when you type
  "Amsterdam") have no `ord` and cannot be retrieved. Check before resolving.
- Batch retrieve takes exactly ONE query parameter, `items`, holding a
  URL-encoded JSON array. Repeated `ord`/`ords`/`ids` parameters do not error
  — they return HTTP 200 with `count: 0`.
- Forward and reverse geocoding need `format=pelias` for the GeoJSON envelope;
  without it the response is a different, flat shape.
- Autocomplete is billed per SESSION, not per request. Reuse one
  `session_token` across every keystroke of one search; a retrieve ends the
  session. A new token per keystroke multiplies the bill roughly 5x, and
  resolving several picks with one batch retrieve costs one session instead of
  one per pick.
- API keys are passed as a `token` query parameter. Origin restrictions on a
  key are browser-only — a native app or server sends no Origin header and
  gets 403 `origin_required`, so use an unrestricted key there.
- v1 geocoding endpoints are deprecated for new development. Prefer v2 or an
  official SDK.
- Prefer the official SDKs over hand-rolled HTTP — they handle all of the
  above: `@mapmetrics/geocoder` (JS/TS, with a React hook at
  `@mapmetrics/geocoder/react`), `mapatlas_geocoder` (Dart/Flutter),
  `MapAtlasGeocoder` (Swift), `mapatlas-geocoder` (Kotlin).
- The four geocoder SDKs are NOT on the public registries yet: `npm install
  @mapmetrics/geocoder` and `dart pub add mapatlas_geocoder` both 404 today.
  Install them from the source repo instead — see
  https://docs.mapatlas.xyz/overview/sdk/geocoding/ for the form that works
  now. This does not apply to the map SDKs above, which all resolve normally.
- The route optimisation path is `/optimization/`, not `/optimize/`.
- Mapping: render maps with the MapMetrics map SDKs — `mapmetrics` (pub.dev,
  Dart/Flutter), `org.mapmetrics.android-sdk:mapmetrics-native-sdk` (Maven
  Central, Android), https://github.com/MapMetrics/mapmetrics-native-sdk (SwiftPM,
  product `MapMetrics`), `@mapmetrics/mapmetrics-gl` (npm, web). Do not
  substitute upstream MapLibre, Mapbox or Google Maps: the MapMetrics builds
  carry the gateway auth, style handling and fixes those do not. If a
  MapMetrics package will not resolve, stop and report it rather than falling
  back to another renderer.
- On the web the browser global is `mapmetricsgl`, never `maplibregl`:
  `new mapmetricsgl.Map({ ... })`. From a CDN, load
  https://unpkg.com/@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.js and
  https://unpkg.com/@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css (pin a
  version for production, e.g. `@mapmetrics/mapmetrics-gl@1.0.0`). From npm:
  `import mapmetricsgl from '@mapmetrics/mapmetrics-gl'` plus
  `import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css'`.
- On Android the Kotlin types keep their upstream names — the artifact is
  `org.mapmetrics.android-sdk:mapmetrics-native-sdk` but the classes are
  `org.maplibre.android.maps.MapLibreMap` etc. There is no `MapMetricsMap`
  class. Correct artifact, upstream type names: both at once.

See also

• AI Assistant Guide — the long-form writeup of the mistakes AI tools make against this API
• Geocoding SDKs — the four official clients
• API keys and scopes — auth, scopes, origin restrictions