Qartas API Reference

Base URL: https://navigation.wslt.app — all endpoints below are relative to it. Verified against the service source (internal/api/handlers.go, internal/api/tiles.go, cmd/chafmaps-api/main.go, internal/engine/*) and against live responses on 2026-07-31.

Conventions

Auth — every endpoint requires authentication; there is no anonymous access. Two credential forms:

See auth.md for details.

Envelope — JSON endpoints wrap results:

{"status":"success","data":{...},"message":"OK"}
{"status":"error","error":{"code":"CODE","message":"text","details":{...}?},"message":"text"}

Binary endpoints (tiles, glyphs, sprites .png, staticmap) return raw bytes on success; their parameter/upstream errors are a bare HTTP status with no body (auth-layer errors on those routes do use the JSON envelope).

Request correlation — every response carries X-Request-ID (either your well-formed UUID X-Request-ID request header echoed back, or a generated one). Quote it in support requests.

Limits — request bodies are capped at 1 MB; the whole request times out at 30 s (504 REQUEST_TIMEOUT) — both operator-configurable (CHAFMAPS_API_REQUEST_TIMEOUT_SECONDS, default 30). Per-minute rate limits and daily quotas: rate-limits-and-plans.md.

Zero coordinates — JSON body fields marked required below use binding validation that treats an absent field and a literal 0 identically: a coordinate of exactly 0 is rejected (400 VALIDATION_ERROR). Coordinates (0,0) ("null island") are never valid input anywhere on this API.

Service off-switch — if the engine is disabled on the server, every /maps/v1 route answers 503 MAPS_UNAVAILABLE.

GET /maps/v1/autocomplete

Search-as-you-type place suggestions.

Query parameters

Response — 200

{
  "predictions": [
    {
      "place_id": "g_0x151b5fb85d7981af:0x631c30c0f8dc65e8",
      "name": "Amman",
      "address": "Al-Matar Street, Amman",
      "distance_meters": 1200,
      "lat": 31.9543786,
      "lng": 35.9105776,
      "ownership_tier": "seed",
      "driver_verifications": 0
    }
  ],
  "source": "redis",
  "served_in_ms": 0,
  "budget_expired": false
}

Errors

401 (auth), 429 RATE_LIMIT_EXCEEDED/MAPS_QUOTA_EXCEEDED, 503 AUTOCOMPLETE_BACKPRESSURE / AUTOCOMPLETE_UNAVAILABLE / AUTOCOMPLETE_DISABLED, 502 AUTOCOMPLETE_FAILED. See errors.md.

POST /maps/v1/geocode

Forward geocoding: free-text address → coordinates. (Implemented as autocomplete → top hit → place-details enrichment; if enrichment fails you still get the autocomplete hit's coordinates.)

Body

Response — 200

{
  "matched": true,
  "formatted_address": "Desert Highway, Amman",
  "place_id": "g_0x151b5402e149d31b:0x1b38522aafb395fc",
  "name": "Queen Alia International Airport (AMM)",
  "lat": 31.7216982,
  "lng": 35.9964563,
  "source": "chafmaps_autocomplete"
}

Errors

400 VALIDATION_ERROR (missing/empty address), 401, 429, 503 GEOCODE_BACKPRESSURE / GEOCODE_UNAVAILABLE / GEOCODE_DISABLED, 502 GEOCODE_FAILED.

POST /maps/v1/reverse

Reverse geocoding: coordinates → address.

Body

Response — 200

{
  "lat": 31.9539,
  "lng": 35.9106,
  "formatted_address": "CAC - المركز الزراعي الشامل، عمّان",
  "place_id": "g_...",
  "source": "fresh"
}

source: "no_address" is a real answer ("nothing is here" — open water, unmapped area), served 200. Do not treat it as a failure or retry it.

Errors

400 VALIDATION_ERROR, 401, 429, 503 REVERSE_BACKPRESSURE (Retry-After: 2) — momentary saturation, retry; 503 REVERSE_UNAVAILABLE (Retry-After: 5) — all sources failed, retry later; 502 REVERSE_FAILED.

POST /maps/v1/directions

Driving directions between two points, optionally via up to 4 waypoints.

Body

Origin ≈ destination (and no waypoints) is rejected: 400 SAME_POINT.

Response — 200, three shapes

1. Normal route (no waypoints, routing succeeded):

{
  "routes": [
    {
      "label": "Fastest",
      "distance_meters": 10562,
      "duration_seconds": 1043,
      "live_traffic_duration_seconds": 1043,
      "polyline": "{\"coordinates\":[[35.9106,31.9539],...],\"type\":\"LineString\"}",
      "maneuvers": [ {"type":"left","instruction":"Turn left onto ...","distance_m":230.0,"duration_s":25.0,"street_name":"..."} ]
    }
  ],
  "distance_meters": 10562,
  "duration_seconds": 1043,
  "polyline": "<primary route's GeoJSON LineString, as a JSON string>",
  "source": "redis",
  "engine": "google",
  "ownership_tier": "seed",
  "served_at": "2026-07-31T22:24:07Z",
  "served_in_ms": 3
}

2. Degraded straight line (timeout or all-sources failure — still 200):

{
  "polyline": "{\"type\":\"LineString\",\"coordinates\":[[35.9106,31.9539],[35.8340,31.9720]]}",
  "distance_meters": 7423,
  "duration_seconds": 1856,
  "routes": [],
  "partial": true,
  "reason": "degraded",
  "source": "server_straight",
  "elapsed_ms": 8000
}

distance_meters is the straight-line (haversine) distance; duration_seconds is a rough estimate (distance ÷ 4 m/s, minimum 30 s).

🔴 Never render a partial: true polyline as a road route. Show distance/ETA if useful and re-fetch shortly — the gather keeps running server-side, so the retry is usually a cache hit. Detect this shape by partial == true or source == "server_straight".

3. Multi-leg (any waypoints present):

{
  "polyline": "{\"type\":\"MultiLineString\",\"coordinates\":[[[lng,lat],...],[[lng,lat],...]]}",
  "distance_meters": 14210,
  "duration_seconds": 1580,
  "legs": 2,
  "partial": false,
  "source": "maps_v1_multileg",
  "elapsed_ms": 950
}

polyline is a GeoJSON MultiLineString (one member per leg, serialized as a JSON string). partial: true + source: "maps_v1_multileg_partial" means at least one leg degraded to a straight line — the same "don't draw as a road" rule applies to that response. No routes[] array on this shape. Multi-leg totals are a route preview — do not use them as a pricing/fare anchor.

Errors

400 VALIDATION_ERROR / SAME_POINT / TOO_MANY_WAYPOINTS / BAD_WAYPOINT / ENRICH_MANEUVERS_UNSUPPORTED, 401, 422 DIRECTIONS_UNROUTABLE (no route exists between the coordinates — don't retry unchanged), 429, 503 DIRECTIONS_BACKPRESSURE (Retry-After: 5). Note: generic routing failures do not produce a 5xx — they produce the degraded 200 above.

POST /maps/v1/prefetch-directions

Fire-and-forget cache warm-up. Same body and validation as /directions (including the 4-waypoint cap and enrich_maneuvers rejection). The server validates, queues the gather(s) in the background, and answers immediately — you never wait for routing.

Response — 200

{"queued": true, "legs": 1}

or, when the server's bounded prefetch pool is saturated (not an error — the prefetch is a hint, not a promise):

{"queued": false, "reason": "prefetch_saturated"}

legs = 1 + number of waypoints. Background gathers are capped server-side (default 16 concurrent, 20 s timeout each; env CHAFMAPS_API_PREFETCH_MAX_CONCURRENT / CHAFMAPS_API_PREFETCH_TIMEOUT_MS).

Errors

Same validation errors as /directions; 401; 429.

GET /maps/v1/place/{id}

Full details for a place ID (from autocomplete/geocode).

Path & query parameters

Response — 200

{
  "place_id": "0x151b5f96539bcc23:0x83d61bcf8e637e6d",
  "name": "Amman Citadel",
  "address": "Amman Citadel, K. Ali Ben Al-Hussein St. 146, Amman",
  "lat": 31.9543163,
  "lng": 35.9365046,
  "phone": "+962 6 463 8795",
  "category": "Amman Citadel",
  "rating": 4.5,
  "ownership_tier": "enriched",
  "driver_verifications": 0
}

Errors

400 MISSING_ID / BAD_PLACE_ID, 401, 429, 503 PLACE_UNAVAILABLE (Retry-After: 5), 503 PLACE_DISABLED / PLACE_BACKPRESSURE, 502 PLACE_FAILED.

GET /maps/v1/place-photos

Photos for whatever place is at a coordinate (reverse-geocode → place-resolve → photos, composed server-side, best-effort).

Query parameters

Response — 200

{"place_id": "g_0x151b5fe8b12bd0c7:0x974306aae2775390", "photos": ["https://lh3.googleusercontent.com/...", "..."]}

Errors

400 MISSING_COORDS, 401, 429.

POST /maps/v1/tile-token

Mints the short-lived HMAC tile token that authorizes URL-parameter tile access. No request body.

Response — 200

{
  "token": "bWFwc2tleTpkYTRkMWU3Ni0...",
  "expires_at": "2026-07-31T22:24:16.837974336Z"
}

Errors

401, 429, 500 TILE_TOKEN_FAILED (server misconfiguration), 503 MAPS_UNAVAILABLE.

GET /maps/v1/tiles/{z}/{x}/{y}[@2x|@3x].png

Raster basemap tiles (Web-Mercator XYZ scheme).

Path parameters & auth

Auth: X-API-Key header or ?t=<tile token>. Anonymous → 401 AUTH_REQUIRED (JSON envelope).

Optional request header X-Chaf-Prefetch: <any value> marks speculative (pre-warming) traffic: cache misses are routed to a free prefetch pool, and a degraded stand-in tile becomes a 503 instead of an image (a prefetcher has no impatient viewer). Always send it from prefetch code paths.

Response — 200

Raw image bytes. Notable headers:

Errors (bare status, no JSON body — except auth)

GET /maps/v1/vector/{source}/{z}/{x}/{y} — NOT OFFERED

Registered but not part of the product. On the live deployment it answers:

501 Not Implemented
{"status":"error","error":{"code":"VECTOR_TILES_NOT_SUPPORTED","message":"vector tiles are not offered by this service — the standalone Qartas API serves raster tiles only (tiles/@2x/@3x, style, glyphs, sprites, staticmap). ..."},"message":"..."}

Do not retry a 501. (The route exists so that a self-hosted operator could point CHAFMAPS_VECTOR_TILE_ORIGIN at their own tileserver-gl; the hosted service does not.)

GET /maps/v1/style/{name}

MapLibre GL JSON styles (version 8) whose tile/glyph URLs point back at this API.

Parameters & auth

Note the two different query parameters: ?token= is what gets embedded in the style body; auth for fetching the style itself is X-API-Key or ?t= — same as the rest of the tile family. A typical map-widget call is:

GET /maps/v1/style/raster-nav.json?t=<tile token>&token=<same tile token>

Response — 200

Content-Type: application/json, Cache-Control: private, max-age=60. raster-nav additionally sets Access-Control-Allow-Origin: * (usable from MapLibre GL JS in a browser). Example (raster-nav):

{"version":8,"name":"Qartas SDK Raster Nav",
 "glyphs":"/maps/v1/glyphs/{fontstack}/{range}.pbf",
 "sources":{"g":{"type":"raster","tiles":["/maps/v1/tiles/{z}/{x}/{y}@2x.png"],"tileSize":256,"attribution":""}},
 "layers":[{"id":"g","type":"raster","source":"g"}]}

URLs are relative — they resolve against whatever host served the style (the operator can switch them to absolute via CHAFMAPS_API_PUBLIC_BASE_URL).

GET /maps/v1/glyphs/{fontstack}/{range}

SDF font glyphs for MapLibre text rendering.

Auth: X-API-Key or ?t=. Response: application/x-protobuf, Cache-Control: public, max-age=2592000, immutable.

GET /maps/v1/sprites/{name}

Sprite stub for MapLibre's automatic sprite requests (the bundled styles use no icon layers, so a valid-empty answer is correct).

Auth: X-API-Key or ?t=. Cache-Control: public, max-age=3600.

GET /maps/v1/staticmap

Server-rendered PNG of a route path over the basemap (stitched from real tiles + drawn polyline). This is a genuine per-call render, so it is credentialed like the JSON endpoints (X-API-Key header; a ?t= tile token is not accepted here) and billed to its own "tiles" daily quota bucket (see rate-limits-and-plans.md).

Query parameters

Response — 200

image/png bytes, Cache-Control: public, max-age=86400.

Errors

Bare 400 (bad path), 401 (envelope), 429, bare 502 (render failed — there is no degraded fallback shape for an image).

Health endpoints (no auth)

← Documentation