POST/route

Valhalla RouteRequest JSON (costing may be auto, truck, bicycle, pedestrian, motor_scooter, bus or motorcycle; per-mode costing_options such as pedestrian use_lit/type/max_hiking_difficulty or bicycle bicycle_type/use_roads/use_living_streets/avoid_bad_surfaces/use_hills pass through), optionally extended with top-level avoid and exclude string arrays naming road features to keep off; avoid accepts tolls, highways and ferries and is a PREFERENCE (the engine's use_* factor set to 0, which its own reference says is not guaranteed to avoid them entirely); exclude accepts tolls, highways, ferries, bridges and tunnels and is a HARD exclusion that can answer "no path" and that depends on the routing engine's service_limits.allow_hard_exclusions setting. Both are validated per costing, so a value the engine has no field for is a 400 naming the supported set rather than a silently ignored option, and every response that used either carries a top-level avoid block echoing what was applied. Kerbside arrival uses each location's own preferred_side (same/opposite/either, aliases curb/unrestricted; resolved against the locale's driving side) with street_side_tolerance, street_side_max_distance and street_side_cutoff, optionally extended with a top-level adr vehicle profile object, a top-level truck object accepted as an alias for costing_options.truck on truck costing (merged before the search; a field declared in both places with different values is a 400 naming it, and a top-level truck object on any other costing is a 400), and a top-level rationale: true flag (truck, auto, bicycle, pedestrian and motor_scooter; opt-in because it costs up to 1 + N extra engine calls, and it draws one call of its class per engine computation it performs, at most 8 and typically fewer, reported back in rationale.metering) for a structured rationale.avoided[] block derived by route divergence, with live incidents on the route attached as context where incident data is configured, and a top-level landmarks: true flag for turn instructions anchored to recognisable places ("Turn right just after the Shell garage"), added alongside each manoeuvre's own instruction as landmark_instruction and never replacing it, and a top-level traffic: true flag for a per-leg traffic object (covered_pct, confidence in HERE's bands, sources) saying what speed data stood behind the ETA, plus, only when a live claim stands (date_time.type 0 and a fresh snapshot), a congestion object: direction-matched spans graded moderate, slow or severe by live against typical speed with shape indices for colouring the line, delay_s (time lost against National Highways' own typical speeds on stretches with a live record, England strategic road network only) and live_m; computed from the returned geometry, so it costs no extra engine call and is not metered separately. May also carry an optional top-level emissions object (vehicle_category, fuel, euro_standard) declaring the vehicle for UK clean-air zone assessment, and a top-level avoid_zones: true flag asking the search to keep out of every zone that vehicle would be charged or banned in (applied as exclude_polygons before the route is computed, so no extra engine call and no extra metering). May also carry a top-level scenic extension (true, or an object with max_extra_minutes) on auto costing, which adds a scenic block saying whether a prettier route exists, what makes it prettier in one spoken-ready sentence measured from the basemap tiles, and how many extra minutes it costs. The route in trip is never changed by it: the scenic route rides alongside in scenic.alternative.trip. An offer that cannot state its reason is not made, and the flag draws at most two extra route computations, reserved up front and refunded to what was drawn. alternates with date_time type 0 (leave now) on an origin plus destination request (not truck costing) returns the live-aware route plus up to alternates distinct alternatives, each re-costed on its exact path with the same date_time so every duration uses live and predicted speeds where covered, sorted fastest first (trip is the fastest, save for the turnaround case below); billed as one route call, and if the alternatives cannot be costed the time-dependent route comes back alone. Any other date_time type, or a multi-stop request, returns one route when a date_time is set, because the engine's time-dependent search has no alternates. For auto, motorcycle and motor_scooter, when the engine's first choice turns off a road and comes straight back onto it, two same-side turns at most 50 m apart that turn the car round (a turnaround loop through a slip or side road, which the engine prices as two ordinary turns), and an alternate in the same response costs at most 120 s more, that alternate becomes trip, the looping route stays in alternates, and a top-level turnaround block gives loop_at, road, seconds_added and threshold_s. No extra engine call and no extra metering; without alternates nothing changes. Pedestrian routes also accept costing_options.pedestrian.use_hills (0 to 1; a wheelchair route that omits it is sent 0), max_grade_pct (whole percent 1 to 90, mapped onto the engine's max_grade, which the engine accepts and does not enforce yet: the response says so in grade.cap) and surface_quality ("avoid" or "ignore", wheelchair only), plus a top-level grade_report: true flag for the grade block (automatic on wheelchair routes and whenever a grade cap is set). At most 500 locations (waypoints) per request. The routing engine takes 20 per call, so longer lists are cut at break waypoints, routed concurrently and spliced into one continuous route, and billed one call per started block of 20 waypoints