HTTP API reference

Request conventions #

Prerequisites: the maps origin and a key with the scopes listed below. All URLs are relative to that maps root, not the portal. Send JSON for pack POST requests and X-API-Key where possible. Coordinates use lng,lat; bounding boxes use [W,S,E,N]. Service responses are JSON/GeoJSON. Maps CORS permits GET, HEAD, POST and OPTIONS, including Range and X-API-Key headers.

curl --fail-with-body -H "X-API-Key: YOUR_API_KEY"   "https://maps.example/depth?at=126.8,10"

The v1 release/pack manifests carry schemaVersion:1. Existing search/route/depth responses do not all carry schemaVersion; do not require a field the service does not emit. Within the v1 client contract, additions should remain compatible and clients should ignore unknown fields.

Search, routing and depth endpoints #

Place properties: name, label, kind, category, address, osm; optional GeoJSON bbox. Address fields are optional. Route properties: mode, distance_m, duration_s, depart_at, arrive_at, legs[]. Each leg has distance_m, duration_s and steps[{instruction,distance_m,duration_s,streets,location}]. Search/route features can be empty; handle that before indexing features[0]. See service chapters for complete JavaScript and curl examples.

Release and static resource endpoints #

Style raw=1 leaves __MAP_BASE__ intact. base overrides the data-resource root; key is propagated into generated URLs. Styles and dated file URLs are discussed in Styles and overlays. The internal /_auth nginx subrequest is not an application endpoint. Photon and Valhalla are not public APIs.

Pack endpoints #

{
  "release": "current",
  "bbox": [123.6, 10.1, 124.1, 10.6],
  "shore": [[123.88, 10.28, 123.95, 10.35]],
  "layers": ["base", "gmrt", "contours"],
  "styles": ["dark", "light"],
  "dryRun": true
}

Required: bbox. Defaults: release current, no shore boxes, layers base/gmrt/contours, styles dark/light, dryRun false. Discover optional layers first. POST returns 201 for a new build or 200 for a cached build/dry run. Dry-run fields include schemaVersion,dryRun,packId,release,cached,bbox,shore,layers,styles,files,totalBytes,limits. It has no downloadable pack until a build completes. Limits and the full download recipe are in Download offline maps.

Errors, HTTP caching and Range #

Errors generally include error; pack and authentication errors also include code. Gateway static-file errors may be text/HTML: do not assume every error body is JSON. Current release metadata should be refreshed; named release files are immutable under the client contract. Retained releases and pack caches can disappear, returning 404. Check response cache headers instead of inventing a permanent retention guarantee.

Resume with Range: bytes=<offset>-. A 206 response must match Content-Range; a 200 response means restart the file. Preserve ETag, Content-Length, Content-Range and Accept-Ranges through gateways and CORS. Do not gzip PMTiles or cache partial HTTP responses as whole files. OPTIONS preflights are answered without a key.