Optimize API

Unmap Optimize assigns shipments to vehicles and orders their stops. A shipment is a pickup, a delivery, or a paired pickup and delivery. The solver looks for a low-cost plan that respects your time windows, load capacities, driver breaks and route limits, and returns one route per vehicle.

The endpoint is live at POST https://api.unmap.dev/optimize. It accepts the Google Maps Platform Route Optimization OptimizeToursRequest format and returns an OptimizeToursResponse. REST integrations can use Unmap's host and API key, subject to the supported fields and behaviour differences. Unmap is not affiliated with or endorsed by Google.

Use Optimize for fleet assignment or planning with time windows, capacities or breaks. For the stop order of a single vehicle without those constraints, use /optimized-route.

To try a request without writing code, open the Optimize playground: paste a request or pick one of the worked examples, run it with your key, and see every route on a map with its cost, times and skipped shipments.

This example assigns two parcels to one van in downtown Calgary. It uses straight-line travel at 10 metres per second, so it does not depend on the road network. Remove useGeodesicDistances and geodesicMetersPerSecond to plan with road travel times instead. Set UNMAP_API_KEY for curl, or key for TypeScript, to your API key. Set the model's global start and end times to the day you want to plan.

curl -X POST "https://api.unmap.dev/optimize" \
  -H "X-API-Key: $UNMAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "useGeodesicDistances": true,
    "geodesicMetersPerSecond": 10,
    "model": {
      "globalStartTime": "2026-10-13T15:00:00Z",
      "globalEndTime": "2026-10-14T03:00:00Z",
      "shipments": [
        { "label": "parcel-1", "deliveries": [{ "arrivalLocation": { "latitude": 51.0478, "longitude": -114.0593 } }] },
        { "label": "parcel-2", "deliveries": [{ "arrivalLocation": { "latitude": 51.0375, "longitude": -114.0814 } }] }
      ],
      "vehicles": [
        { "label": "van-1", "startLocation": { "latitude": 51.0447, "longitude": -114.0719 }, "costPerKilometer": 1 }
      ]
    }
  }'

import { optimizeTours } from "@unmap/routing";
 
const { response, billableShipments } = await optimizeTours(
  {
    useGeodesicDistances: true,
    geodesicMetersPerSecond: 10,
    model: {
      globalStartTime: "2026-10-13T15:00:00Z",
      globalEndTime: "2026-10-14T03:00:00Z",
      shipments: [
        { label: "parcel-1", deliveries: [{ arrivalLocation: { latitude: 51.0478, longitude: -114.0593 } }] },
        { label: "parcel-2", deliveries: [{ arrivalLocation: { latitude: 51.0375, longitude: -114.0814 } }] },
      ],
      vehicles: [
        { label: "van-1", startLocation: { latitude: 51.0447, longitude: -114.0719 }, costPerKilometer: 1 },
      ],
    },
  },
  { key },
);

The response below comes from a local run of this request through the same pipeline and solver. Visit order and timings may vary between runs. The solver uses a time budget to search for a lower-cost plan.

// 200, with X-Unmap-Billable-Shipments: 2
{
  "routes": [
    {
      "vehicleIndex": 0,
      "vehicleLabel": "van-1",
      "vehicleStartTime": "2026-10-13T15:00:00Z",
      "vehicleEndTime": "2026-10-13T15:04:47Z",
      "visits": [
        { "shipmentIndex": 0, "isPickup": false, "visitRequestIndex": 0, "startTime": "2026-10-13T15:01:35Z", "detour": "0s", "shipmentLabel": "parcel-1" },
        { "shipmentIndex": 1, "isPickup": false, "visitRequestIndex": 0, "startTime": "2026-10-13T15:04:47Z", "detour": "183s", "shipmentLabel": "parcel-2" }
      ],
      "transitions": [
        { "travelDuration": "95s", "travelDistanceMeters": 946, "waitDuration": "0s", "breakDuration": "0s", "delayDuration": "0s", "totalDuration": "95s", "startTime": "2026-10-13T15:00:00Z" },
        { "travelDuration": "192s", "travelDistanceMeters": 1923, "waitDuration": "0s", "breakDuration": "0s", "delayDuration": "0s", "totalDuration": "192s", "startTime": "2026-10-13T15:01:35Z" },
        { "travelDuration": "0s", "travelDistanceMeters": 0, "waitDuration": "0s", "breakDuration": "0s", "delayDuration": "0s", "totalDuration": "0s", "startTime": "2026-10-13T15:04:47Z" }
      ],
      "metrics": {
        "performedShipmentCount": 2,
        "travelDuration": "287s",
        "waitDuration": "0s",
        "delayDuration": "0s",
        "breakDuration": "0s",
        "visitDuration": "0s",
        "totalDuration": "287s",
        "travelDistanceMeters": 2869
      },
      "routeCosts": { "model.vehicles.cost_per_kilometer": 2.869 },
      "routeTotalCost": 2.869
    }
  ],
  "metrics": {
    "aggregatedRouteMetrics": {
      "performedShipmentCount": 2,
      "travelDuration": "287s",
      "waitDuration": "0s",
      "delayDuration": "0s",
      "breakDuration": "0s",
      "visitDuration": "0s",
      "totalDuration": "287s",
      "travelDistanceMeters": 2869
    },
    "skippedMandatoryShipmentCount": 0,
    "usedVehicleCount": 1,
    "earliestVehicleStartTime": "2026-10-13T15:00:00Z",
    "latestVehicleEndTime": "2026-10-13T15:04:47Z",
    "costs": { "model.vehicles.cost_per_kilometer": 2.869 },
    "totalCost": 2.869
  }
}

• routes: one per vehicle, in request order. visits is the order to drive, each with the time service starts. transitions has one more entry than visits: the legs before each visit and the leg to the vehicle's end.
• The van has no endLocation, so its route ends at its last stop and the final transition has zero travel time and distance. Set endLocation to bring it back to the depot.
• metrics.totalCost includes route costs and penalties for skipped optional shipments. Here it is costPerKilometer multiplied by the distance travelled. Costs use the units you choose and do not represent API charges. Response timestamps are RFC 3339 in UTC; durations are strings in seconds, such as "95s".
• Unserved shipments appear in skippedShipments; reasons may be absent when no specific cause can be identified. A shipment without penaltyCost is mandatory unless ignore: true. If the solver cannot serve all mandatory shipments, the request fails with 400 FAILED_PRECONDITION.

POST /optimize
POST /v1/projects/{project}:optimizeTours
POST /v1/projects/{project}/locations/{location}:optimizeTours
POST /projects/{project}:optimizeTours
POST /projects/{project}/locations/{location}:optimizeTours

All five paths accept the same request and return the same response format. Use /optimize for new integrations. The other four support existing Google Route Optimization REST integrations. {project} and {location} are ignored, as is parent in the body, which produces a warning. The API key identifies the account that runs and pays for the request. Only the :optimizeTours method exists; any other method suffix is a 404 NOT_FOUND.

Send the key as Authorization: Bearer <key>, X-API-Key, X-Goog-Api-Key or ?key=. Keep the key out of the URL on server calls. See Authentication.

The body is JSON, at most 4 MiB (a larger one is a 413). Field names may be camelCase or snake_case; the response is camelCase. Every response the Optimize handler writes, a solve or one of its errors, carries Cache-Control: no-store; a refusal from the key check in front of it, such as a 401, carries the gateway's usual headers instead.

Travel times

A request takes its travel times from one of three places:

• The road network (the default). Driving times and distances from the same Canada road graph as Routing, at free-flow speeds. considerRoadTraffic is accepted and ignored, with a warning when set to true. Stops must be near roads in Canada, and each vehicle must be able to reach its assigned stops. Local routing on an island can work even when the island has no road connection to the mainland. An unreachable mandatory shipment fails the request with 400 FAILED_PRECONDITION; an unreachable optional shipment is skipped. Road travel supports at most 200 distinct locations per request, or the plan's lower location limit. For larger requests, use straight-line travel or your own matrices. Two stops more than 1,000 km apart in a straight line are treated as unreachable from each other, and a request spread that widely can be refused as too large for one solve; split it by region.
• Straight lines. useGeodesicDistances: true with geodesicMetersPerSecond (at least 1): great-circle distance at a fixed speed. It works anywhere, including outside Canada.
• Your own matrices. model.durationDistanceMatrices with durationDistanceMatrixSrcTags and durationDistanceMatrixDstTags. Every stop and vehicle is then placed by tags instead of coordinates, and one matrix per vehicleStartTag gives different vehicles different travel.

Vehicles drive (travelMode DRIVING). Unmap adds one field to the vehicle, unmapProfile, which names the road profile; auto is the only value today.

With populatePolylines: true, Unmap attempts to add routePolyline.points to each used route. It is an encoded polyline at precision 5, drawn along Canadian roads. If drawing fails or runs out of time, the route remains valid and returns without a polyline, with a ROUTE_POLYLINE_UNAVAILABLE warning. For geodesic requests, a road polyline does not change the straight-line travel times or distances used to plan the route. Requests with your own matrices have no coordinates and return no polylines.

What it plans

Supported today:

• Shipments with one pickup, one delivery, or both (a pair is served by one vehicle, pickup first), each visit with a location, a service duration and hard timeWindows.
• Loads: loadDemands on the shipment against loadLimits (maxLoad) on the vehicle, by load type name.
• Optional shipments: penaltyCost adds a cost when a shipment is skipped. The solver may skip it to reduce total cost, to satisfy constraints, or because it cannot find a plan that includes it within its time budget. ignore: true excludes a shipment from planning, with no penalty.
• allowedVehicleIndices to restrict which vehicles may serve a shipment.
• Vehicles with start and end locations (or open ends), one start and one end time window, fixedCost, costPerHour, costPerTraveledHour and costPerKilometer.
• Hard routeDurationLimit, travelDurationLimit and routeDistanceLimit.
• Soft time windows on visits and on a vehicle's start and end (softStartTime, softEndTime and their costs per hour), soft route and travel duration limits, a soft route distance limit and a soft maximum load, each reported under its own key in metrics.costs.
• Driver breaks: breakRule.breakRequests, each with an earliest and latest start and a minimum duration.
• Labels on the request, shipments, visits and vehicles, echoed in the response.
• searchMode: RETURN_FAST stops improving soon after a first plan, CONSUME_ALL_AVAILABLE_TIME uses the whole timeout.

Enum fields accept the name or its integer, as Google's clients send them ("travelMode": 1).

Not yet: quadratic soft duration limits, more than one pickup or delivery alternative per shipment, more than one start or end window per vehicle, shipment types and precedence rules, injected solutions, and walking. Each refuses with FIELD_NOT_SUPPORTED_YET or VALUE_NOT_SUPPORTED_YET rather than being silently dropped, because a plan that ignored one of your constraints would be wrong without telling you. Like quadratic soft duration limits, routeDistanceLimit.costPerKilometerBelowSoftMax is refused, but for good and with INVALID_VALUE: GMPRO does not support it either. A Google place ID is refused too: geocode the address with /geocode/search and send coordinates. Field support lists each field and its status.

Send "solvingMode": "VALIDATE_ONLY" to check a request. Nothing is fetched or solved, and it is never billed. A valid request answers 200 with {}. An invalid one answers 200 with every problem found, up to maxValidationErrors (default 100):

// 200
{
  "validationErrors": [
    {
      "code": 11,
      "displayName": "MISSING_REQUIRED_FIELD",
      "fields": [{ "name": "geodesicMetersPerSecond" }],
      "errorMessage": "geodesicMetersPerSecond is required when useGeodesicDistances is true."
    }
  ]
}

In the default solve mode, these problems return 400 INVALID_ARGUMENT, with one field violation per error. VALIDATE_ONLY checks the request's fields and constraints; it does not check road reachability or whether the fleet can serve every shipment together. Authentication, body parsing, body size and shipment or vehicle count limits still apply and can return non-200 responses before validation.

Limits per plan

• Shipments counts every entry in model.shipments, ignored ones included. Locations is the distinct places travel is needed between, after duplicates are merged. A request over a count is a 400 INVALID_ARGUMENT that names the limit; split it into smaller requests.
• On every plan, a request may use at most 16 distinct load type names across all its loadDemands and loadLimits keys. One more is a 400 INVALID_ARGUMENT (OUT_OF_RANGE).
• Travel matrices may contain at most the plan's location limit squared in total cells: 10,000 for Hobby, 250,000 for Indie and 1,000,000 for Growth. Multiple vehicle matrices share this limit. The 4 MiB body limit also applies to supplied matrices.
• Longest solve caps timeout. A longer one is clamped, with a Warning: 299 - "timeout clamped to 30s for this plan" header and a TIMEOUT_CLAMPED warning. With no timeout, the solve gets min(cap, max(2, ceil(visits / 25))) seconds, where visits are the pickups and deliveries in the request.
• Solves at once is per account, across all its keys. One more is a 429 RESOURCE_EXHAUSTED with Retry-After.
• Road travel and the solver's response share a 140-second budget. A stage that exceeds its allotted time returns 504 DEADLINE_EXCEEDED. Optional polyline generation has an additional 30 seconds, for a total budget of up to 170 seconds. A missing polyline never fails the solve.

These are starting values, set before the service has been measured under production load, and may change.

Pricing

One performed shipment is one call from your plan's included calls, the same pool tiles, geocoding and routing draw on. A performed shipment is one that is visited on a route in a successful (200) solve. Past the included calls, Indie and Growth bill overage at their usual per-call price, and Hobby stops. See Plans & Limits.

Free:

• VALIDATE_ONLY, whatever it finds.
• Every response that is not a 200: validation errors, limits, timeouts, failures.
• Every shipment in skippedShipments, ignored or not served.
• A shipment re-solved within 24 hours of the solve that first billed it.

Unlike other endpoints, Optimize bills a request from a dev origin (localhost, *.pages.dev, *.workers.dev) like any other. The free re-solve above keeps iterating on the same request cheap.

Re-solves. Dispatchers re-plan when a window moves or a driver calls in sick, and those are still the same deliveries. So a shipment with a label is recognised by its label plus its visit locations, and one without a label by its whole content. Within 24 hours of the solve that first billed it, the same shipment is free; the window is not extended by a re-solve. A recycled label on different stops is a new shipment. When the request brings its own matrices, the identity also covers the matrices and each vehicle's startTags and endTags, so new travel data, or a vehicle switched to another matrix, bills again.

The X-Unmap-Billable-Shipments response header reports the billable count, including 0. Before road travel or solving, Unmap checks whether the remaining quota or spend cap covers every new, non-ignored shipment in the request. Optional shipments count in this estimate even if the solver might skip them. If the estimate exceeds the available calls, the request returns 429 RESOURCE_EXHAUSTED with a top-level code of quota_exceeded or spend_cap.

Re-solve discounts apply across an account's keys. Duplicate shipments in one request count as separate units. If the discount lookup is unavailable after a successful solve, all performed shipments count as billable; check X-Unmap-Billable-Shipments for the actual count.

Response headers

Warnings never change the response body, which stays the shape a Google client expects. The codes are FIELD_IGNORED (an accepted field Unmap cannot honour), TIMEOUT_CLAMPED, ROAD_TRAVEL_DEGRADED and ROAD_TRAVEL_UNCONFIRMED (a routing budget, not the road network, decided that some cells were unreachable, so a skipped stop may be servable; split the request), ROUTE_POLYLINE_UNAVAILABLE, and WARNINGS_TRUNCATED. A browser can read all four headers: the gateway exposes them through CORS.

Errors

Errors on these paths use Google's error shape, with the gateway's string code beside it, so a Google client and an Unmap client both read them. The status is in error.status (INVALID_ARGUMENT, FAILED_PRECONDITION, RESOURCE_EXHAUSTED and so on), and validation errors list one fieldViolations entry per problem, with the exact field path. Where Google may answer 200 with a mandatory shipment skipped, Unmap refuses with 400 FAILED_PRECONDITION.

Errors has the full body, every status, validation code, warning and skip reason, with the cause and the fix.

npm i @unmap/routing

pnpm add @unmap/routing

yarn add @unmap/routing

bun add @unmap/routing

optimizeTours() in @unmap/routing sends the key in X-API-Key and returns the Unmap response in Google's format, alongside the parsed response headers. It ships in @unmap/routing and @unmap/sdk from 0.21.0.

import { optimizeTours, UnmapOptimizeError } from "@unmap/routing";
 
try {
  const { response, warnings, billableShipments, timeoutClamped } = await optimizeTours(
    {
      timeout: "10s",
      model: {
        shipments: [{ label: "order-1", deliveries: [{ arrivalLocation: { latitude: 51.05, longitude: -114.07 } }] }],
        vehicles: [{ label: "van-1", startLocation: { latitude: 51.04, longitude: -114.06 } }],
      },
    },
    { key },
  );
  console.log(response.routes, warnings, billableShipments, timeoutClamped);
} catch (e) {
  if (e instanceof UnmapOptimizeError) console.error(e.status, e.googleStatus, e.details);
}

• The same call is router.optimizeTours(request) on a Router, and unmap.router.optimizeTours(request) from @unmap/sdk.
• warnings is the parsed X-Unmap-Optimize-Warnings header, billableShipments the parsed X-Unmap-Billable-Shipments, and timeoutClamped with clampedTimeoutSeconds say whether your timeout was shortened.
• A failure throws UnmapOptimizeError: status is the HTTP status, code the gateway's string code, googleStatus Google's status name and details Google's error.details. 429, 502, 503 and transport failures are retried by default.

Field support

Every field of the OptimizeToursRequest format used by the Google Maps Platform Route Optimization API, and what Unmap Optimize does with it. Field names and nesting follow Google's public REST reference; the descriptions are Unmap's own. Unmap is not affiliated with or endorsed by Google.

This section is generated from the validator's field table, and repository checks keep it in sync. There are 191 rows: 126 supported, 16 ignored, 5 rejected, 30 planned (V2), 14 planned (V3).

How to read the tables

A path such as model.shipments[].deliveries[].timeWindows[].startTime names one field: name[] is an element of an array, and name{} is a value of a map whose keys are yours (load type names, such as loadLimits{}). Fields under a refused or ignored field are not listed, because nothing below it is read.

Rules for the whole body:

• Field names may be camelCase or snake_case. Sending both spellings of one field in the same object is a CONFLICTING_FIELD_NAMES error. Map keys and string values are never rewritten.
• A field that is not in these tables is an UNKNOWN_FIELD error, so a typo never silently drops a constraint.
• Durations are strings such as "300s" or "1.5s". Timestamps are RFC 3339 strings or { "seconds": ..., "nanos": ... }. 64-bit integers may be decimal strings or JSON integers up to 2^53 - 1.
• Validation stops after maxValidationErrors errors (default 100, at most 10,000).
• A request may use at most 16 distinct load type names, counted over every loadDemands and loadLimits key in the model. The first name past that is an OUT_OF_RANGE error.
• A Google place ID (placeId) is PLACE_ID_NOT_SUPPORTED; geocode the address with /geocode/search and send coordinates. No field takes a URI: the batch methods that read gs:// Cloud Storage URIs are not available (they answer 404), and GCS_URI_NOT_SUPPORTED is reserved for them; nothing returns it today.

Every error code is explained in Errors.

Field support describes validation and supported behaviour. It does not guarantee that a request has a feasible solution. populatePolylines attempts road geometry for routes with coordinates; supplied-matrix requests return no polylines. See travel times and limits per plan.

Request fields

Model fields

Shipment fields

Vehicle fields

Next steps

• Examples, each a complete request to copy: last-mile deliveries, field service with breaks, and a pickup and delivery courier.
• Errors: every error, warning and skip reason.
• From Google Route Optimization: moving an existing integration.