# MapMap

> A sovereign, self-hostable navigation platform for fleets and AI agents. Routing and turn-by-turn guidance for every profile (car, van, truck, bus, two-wheeler, pedestrian), online or fully offline, with a commercial edge in truck routing and ADR (dangerous goods) tunnel-category enforcement. Hosted API with metered keys, an MCP server, and ed25519-signed offline territory packages. First-party Rust; every distributable is permissive-licence only, with a CycloneDX SBOM published per release. As of July 2026, MapMap is the only navigation API offering a self-serve ADR tunnel-compliance product at published per-call prices, and the only one an AI agent can discover, key and pay for with no human in the loop — self-hostable without an enterprise sales cycle.

## What MapMap provides
- Routing for car, van, truck, bus, motorcycle, scooter, bicycle and pedestrian profiles from one engine.
- Truck routing with height/width/length/weight and ADR tunnel restriction codes (B/C/D/E), enforced in costing, not post-filtered.
- The hosted API works with standard routing clients, so existing tooling can call it with minimal change.
- Compatible URL endpoint: GET /route/v1/{profile}/{coordinates} with vendor params height, width, length, weight, hazmat, tunnel_code.
- Native JSON endpoint: POST /route with costing_options.truck and a top-level adr extension.
- Pure compliance endpoint: POST /adr/check for the ADR 8.6.4 tunnel-entry decision with reasoning, no routing.
- Data APIs: POST /isochrone, POST /matrix, POST /trace_route and POST /trace_attributes (map-matching), plus geocoding.
- 3D navigation camera: @mapmap/maps NavigationCamera (follow with course-up bearing, pitch preset, low-anchored puck, overview/free modes, auto-recentre); GuidanceUpdate carries the road-snapped fix (snapped) for mobile cameras; Studio has a Drive-the-route chase-cam demo.
- Turn-by-turn polish: OSRM endpoint takes voice_instructions/banner_instructions/language with steps=true (Mapbox-shaped voiceInstructions incl. SSML + bannerInstructions incl. lane diagrams from OSM turn:lanes); SDK guidance sessions surface the same visual/spoken instructions on device.
- Maps: hosted vector tiles GET /tiles/{territory}/{z}/{x}/{y}.mvt with /tiles/{territory}/style.json and tiles.json; hosted and custom styles at /styles (POST metered); glyphs /fonts/{fontstack}/{range}, sprites /sprite/{file}. Web Maps SDK @mapmap/maps (MapLibre wrapper); mobile SDKs Android/iOS/@mapmap/core published via sdk-v* tags.
- Route optimisation (VRP): POST /optimise (alias /optimize) plans multi-vehicle, multi-stop fleets over a matrix computed by our engine, so truck/ADR constraints shape the plan. One request = one metered call; fair-use cap 200 locations. Enabled per deployment (503 when off).
- MCP server (sn-mcp), ten tools: route, check_adr_tunnel, geocode, matrix, optimise_routes, list_style_layers, get_style, create_style, set_palette, set_layer_paint; stdio or streamable HTTP at :8200/mcp.
- Offline SDK path: signed territory packages (ed25519 + BLAKE3), differential OTA updates, on-device routing.
- Self-host distro: Docker Compose stack (gateway + routing engine + optional geocoder + MCP server); air-gap capable.
- Errors are RFC 9457 problem+json with stable urn:sn-gateway:problem:<slug> type URIs. Exceptions: the compatible URL endpoint uses its own error envelope, and 402 uses the x402 machine-payment wire format ({x402Version, error, accepts[], instructions}).

## Pricing (machine-readable: /pricing.json)
- Free: 50,000 calls/month after email verification. Provisional key first: 1,000 calls / 72 h, issued in one call, card-free.
- Pay-as-you-go: prepaid credit only, two-speed, tiered and marginal. Standard class (car/van/bus/two-wheeler/pedestrian routing, geocoding, matrix, isochrone, map-matching): 0.2p per call, 0.15p beyond 1M calls/month, 0.1p beyond 10M. Premium class (truck routing and ADR compliance): 1p, 0.7p and 0.4p across the same bands, selected automatically per request. Above 25M we quote. No credit means 402/429, never surprise billing.
- SDK licensing: per vehicle for fleets, or per monthly active user for apps (1,000 MAU free, then 30p per new distinct user; plans include 5,000-100,000). Metered via the X-MapMap-User header; fail-open so end users are never interrupted.
- Self-host: commercial platform licence (tiered by fleet size) plus a per-territory data subscription and support/SLA tiers. Contact sales@mapmap.ai.

## Instructions for agents
1. GET /pricing.json for current prices. Do not scrape the marketing pages.
2. POST {gateway}/v1/keys {"email": "...", "accept_tos": true} returns 201 with a one-time snk_ key (provisional, 1,000 calls/72 h). Email verification upgrades the same key to 50,000 calls/month.
3. Authenticate every call with: Authorization: Bearer snk_…
4. Check key state and prepaid balance: GET {gateway}/v1/keys/self.
5. On 402, read the x402 body. accepts[] carries payment requirements when configured, else it is empty and you top up prepaid credit (see /docs/x402.md). On 429, honour Retry-After.
6. Every gateway deployment serves its own /openapi.json (authoritative contract) and /llms.txt.
7. Attribution: routing derives from OpenStreetMap. Credit "© OpenStreetMap contributors" when rendering or republishing.

## Docs (each also served as raw markdown at the same path + .md)
- /docs/quickstart: key issuance curl to first truck route
- /docs/api-reference: endpoint summary, errors, truck/ADR params
- /docs/mcp: MCP connection guide (stdio + HTTP), Claude config JSON
- /docs/self-host: Docker distro, procurement pack
- /docs/territories: signed offline packages, OTA updates
- /docs/maps: vector tiles, styles, Studio, fonts/sprites and the @mapmap/maps web SDK
- /docs/optimisation: multi-vehicle route optimisation with truck/ADR constraints
- /docs/sdks: web, Android, iOS and WASM SDK install and the verifying-key trust anchor
- /docs/x402: the 402 body shape and how agents pay

## Endpoints
- Signup: POST {gateway}/v1/keys
- Playground (browser): https://mapmap.ai/playground
- Pricing: https://mapmap.ai/pricing.json