Documentation menu
POST/optimise
API key required, sent as Authorization: Bearer snk_… or ?api_key=snk_….
Call it
curl -fsS -X POST "https://api.mapmap.ai/optimise" \
-H "Authorization: Bearer $MAPMAP_KEY" \
-H "Content-Type: application/json" \
-d @request.jsonRequest body
application/json
Optimisation problem: vehicles (id, start/end, capacity, skills, time_window, plus breaks, max_travel_time, max_tasks and a costs model), jobs (id, location, service_s, delivery, pickup, skills, time_windows), optional shipments (pickup+delivery pairs), costing (auto|truck|bicycle|pedestrian|motor_scooter), optional Valhalla-style costing_options and an optional top-level adr vehicle profile (as on /route). Set eu_drivers_hours (true or {driving_before_break_s, break_duration_s}) to auto-generate EC 561/2006 rest breaks for windowed vehicles without explicit breaks (single-shift approximation). An optional emissions object (vehicle_category, fuel, euro_standard, as on /route) reports which of the problem's own locations sit in a UK clean-air zone and what this vehicle pays there; avoid_zones: true additionally keeps the internal travel-time matrix out of those zones. Optional territories ([{id, polygon}], GeoJSON [lon, lat] rings) plus per-vehicle territory_ids confine a vehicle to named rounds: it may serve a task only if the task sits inside at least one of its territories, a vehicle with no territory_ids serves anywhere, and a task inside no territory at all is servable by unrestricted vehicles only. Per-vehicle reloads ({max_trips, reload_time_s, depot}) lets a vehicle return to its depot, reload and go out again; the waste-collection tipping round: the vehicle is split into one virtual vehicle per trip and its time_window (which becomes required) is partitioned into consecutive trip windows separated by reload_time_s, so capacity, max_tasks, max_travel_time and costs apply PER TRIP. Optional relax_if_unassigned ({time_windows_by_s, allow_overtime_s}) re-solves ONCE with those caps applied when the first solve leaves work unassigned, keeps the relaxed plan only if it assigns more, and bills two solves when it runs. /optimize is accepted as an alias. Fair use: at most 200 unique locations per request, and no wider than the routing engine's matrix span (1,500 km on the hosted gateway, 400 km stock on a self-host)
The OpenAPI document declares this body as a free-form JSON object with no field list, so there is nothing here to generate a table from. The prose above is what the gateway states about it; the raw document is the authority.
Responses
summary, unassigned and routes[] with ordered steps[] (durations in seconds, distances in metres, locations echoed as {lat, lon}), plus the matrix profile used and, when any location sits in a UK clean-air zone or avoid_zones was set, a zones block naming those zones and the avoidance applied to the matrix. When territories was given, a territories block reports per-territory job counts (inside, assigned, unassigned), the jobs outside every territory, anything no vehicle was allowed to serve, and the semantics in force. When any vehicle declared reloads, each route carries its trip (1-based) beside the caller's own vehicle id, summary.routes counts TRIPS, and a reloads block reports trips used vs allowed, the depot, the trip windows and the sequencing approximation. When relax_if_unassigned was given, a relaxation block states whether a second solve ran, whether its plan is the one returned, what was widened and what is still unassignedmax_matrix_distance (1,500 km on the hosted gateway, 400 km stock on a self-host: the internal matrix is chunked to fit the engine's pair ceiling, but its span cannot be chunked around)Error bodies follow the shared problem model documented on API conventions.
Also under routing
Generated from https://api.mapmap.ai/openapi.json on 2026-09-17 · operationId post_optimise