MapMetrics Atlas API Docs

Appearance

Both copy text to your clipboard — Build with AI copies a setup prompt to paste into Claude Code, Cursor, Codex or Copilot; Copy page as Markdown copies this page to paste into a chat. How it works

Build with AI ​

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.

ToolWhat it does
search_docsRanked full-text search across the docs, with excerpts
get_docThe full markdown of one page
list_docsThe complete page index, optionally by section

No API key — it serves public documentation.

Claude Code

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

Cursor — ~/.cursor/mcp.json

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

Codex — ~/.codex/config.toml

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

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

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

GitHub Copilot — .vscode/mcp.json

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 route optimisation path is `/optimization/`, not `/optimize/`.

See also ​