Routing

traffic: none → route_policy: static (Valhalla). traffic: live → traffic_optimized (TomTom returns geometry, instructions and ETA together) when the key has traffic_routing, the contract is live and the budget allows; otherwise the static route with traffic.applied=false and a traffic.reason (not_entitled, budget_exhausted, provider_error, …) and the UI shows "no live traffic". A destination given as a place routes to its entrance (pedestrian) or vehicle entrance / pickup point (driving) when there is evidence; otherwise to the building or street. If Valhalla is down or does not answer within the routing timeout (5 s by default): 503 routing_unavailable with Retry-After (no straight-line or cached fallback). If too many routing requests are already running (a per-server cap; a request waits at most a few hundred ms for a slot): 503 routing_busy with Retry-After — retry after that many seconds, not at once.

Instructions: ru and en text comes from Valhalla's narrative; Valhalla has no Kazakh, so kk text is rendered by the API from its own kk translation file (same structure for every maneuver). Street names are OSM name as mapped (mostly Kazakh in Almaty and Astana) in every language. Alternatives are only computed for two waypoints (a Valhalla limit); with intermediate waypoints alternatives is ignored.

Waypoint resolution:

• entrance_id (osm.n…): that entrance, for every costing — the caller chose it (e.g. the stairwell whose flat range matches, from GET /v1/places/{id}). An ID that is not an entrance is unresolvable.
• place_id of an address, POI or building, pedestrian: an entrance only with unambiguous evidence — the building has exactly one pedestrian entrance, or exactly one main entrance; otherwise the address / building point. With several stairwells, pass the right one as entrance_id.
• place_id of an address, POI or building, auto / taxi: a vehicle entrance only when routing_verified; otherwise the address / building point.
• place_id of a street: a point on the street (street); of a city, district or microdistrict: its representative point (locality).
• Crowdsourced ugc.* IDs (published places only; reverted ones are unresolvable): the same rules over the place's approved entrances; the place's own point otherwise (building). No crowdsourced entrance is routing_verified yet, so they never steer auto / taxi unless named as entrance_id.

route_policy is always fixed_path: the Valhalla route is rebuilt through TomTom as a path and only its live duration is taken — never a different, faster route, so it must not be called "traffic-avoiding". Route identity is checked (15 m two-way buffer coverage ≥ 95%), otherwise traffic.reason=route_mismatch. Departure must be now (± 5 min); a future time returns 400 future_departure_not_supported. traffic.fetched_at is when we fetched, not the vendor's observation time. Request-specific fields (requested, reason, degraded) are recomputed per request; only successful live durations are shared in cache.

Static (Valhalla) only in the MVP. Metered by element count (sources × targets). Max 100 sources, 100 targets and 2,500 elements per request; larger requests return 400 limit_exceeded. The element budget is reserved before computing; when exhausted: 402 budget_exhausted.

Valhalla map matching. Metered per input point; max 2,000 points. Traces are processed in memory and never logged.

Only points backed by field data, approved submissions or licensed data; none are generated.