# Mapper — notes for agents and embedders

Mapper is a free great-circle mapper at https://mapper.now/ by PNM Now (Sauces 201 LLC). Distances are the shortest path on a sphere (haversine, R = 6371.0088 km). They are unofficial estimates, not ATC routes or tickets. Human-readable overview: https://mapper.now/about.html. Use of the site, share URLs, and `/api/route` is under https://mapper.now/terms.html.

Start with https://mapper.now/llms.txt for the short version.

## URL scheme

Same as the shareable links the site writes to the address bar:

    https://mapper.now/?r=CODE-CODE-CODE&u=mi

- `r` may repeat. Separators inside one `r`: `-`, space, `/`, `>` join stops on the same route; `,` or `;` starts a new route.
- Unknown IATA codes are dropped.
- Default unit miles; default view globe (`v=map` for the flat map).

## HTTP JSON

    GET/POST https://mapper.now/api/route

No authentication. CORS `Access-Control-Allow-Origin: *`.

GET query: `r`, `u`, `v` (same meaning as the map URL).

POST JSON:

    { "routes": [["JFK","LHR","PRG"],["SYD","LAX"]], "unit": "km", "view": "globe" }

`unit`/`view` only affect `mapUrl` (and document the caller’s preference); every response still includes km, mi, and nm on each leg.

200 body (trimmed):

    {
      "ok": true,
      "disclaimer": "...",
      "unit": "mi",
      "routes": [{
        "codes": ["JFK","LHR"],
        "stops": [{"code":"JFK","name":"...","city":"New York","country":"US","lat":40.64,"lon":-73.78}],
        "legs": [{"from":"JFK","to":"LHR","km":5551,"mi":3450,"nm":2997,"estMinutesCruise":448}],
        "totalKm": 5551, "totalMi": 3450, "totalNm": 2997,
        "estMinutesCruise": 448
      }],
      "unknown": [],
      "mapUrl": "https://mapper.now/?r=JFK-LHR"
    }

400 if `r` is missing or every code is unknown. 429 if you exceed 60 req/min/IP.

Airport list: ~7,900 IATA fields from https://mapper.now/data/airports.json (`code,name,city,country,lat,lon`).

## Browser embed (`window.Mapper`)

After `Mapper.ready` resolves:

- `setRoutes([["JFK","LHR","PRG"]], { animate:false })`
- `getRoutes()` → array of code arrays
- `getLegs()` → `{ from, to, fromCity, toCity, fromCountry, toCountry, miles }[]` (statute miles)
- `setUnit("mi"|"km"|"nm")`, `getUnit()`
- `setView("map"|"globe")`, `getView()`
- `setTheme("light"|"dark")`, `getTheme()`
- `onRoutesChange(fn)` → unsubscribe

iOS/Android apps drive the map through this bridge. Unknown codes are dropped.

## Do not use

`POST /api/flight-time` — website-only, origin-checked, calls Claude Haiku. Agents should use `estMinutesCruise` on `/api/route` or say the time is a cruise estimate.

## Product copy constraints

Speak in estimates. Do not claim Mapper shows the path a plane actually flies. Miles-earning figures in the UI are unofficial partner-chart estimates.

## Contact

hello@pnm.now — https://www.pnm.now/