---
title: "Route-optimisation endpoint (see module docs). `/optimize` is an alias."
method: POST
path: "/optimise"
tags: ["routing"]
---

# Route-optimisation endpoint (see module docs). \`/optimize\` is an alias.

`POST /optimise`

## Request

- Base URL: `https://api.mapmap.ai`
- URL: `https://api.mapmap.ai/optimise`
- Auth: one of:
  - HTTP bearer
  - API key in query parameter `api_key`

## Request body

- object

## Response `200`

Optimised plan: `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 unassigned

- object

## Other responses

- `400`: Invalid request, geometry requested, an invalid or unknown territory, a caller skill inside the reserved territory range, a vehicle id inside the reserved virtual-vehicle range, an impossible reload split (max_trips outside 2..=5, no time_window, a start/end that is not the depot, a shift too short for its trips, or a break that fits no trip window), a relaxation cap that is missing, non-positive or above seven days, or the solver rejected the problem
- `401`: Missing or invalid API key
- `422`: More than 200 unique locations (fair-use cap), or a problem spread wider than the routing engine's `max_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), or a problem too large for the solver's cost arithmetic (`optimisation-beyond-solver`, not billed)
- `429`: Quota or rate limit exceeded
- `502`: The VROOM solver is unreachable or failed
- `503`: Optimisation is not enabled on this deployment (SN_VROOM_URL unset)

---

[API](https://skmtc.dev/mapmap/apis/sn-gateway.md) · [All operations](https://skmtc.dev/mapmap/apis/sn-gateway/llms.txt) · [OpenAPI document](https://skmtc.dev/mapmap/apis/sn-gateway/revisions/2293be8b4c38?raw)