Console Buy stops

POST/api/v1/optimize

Optimize a route

Compute the optimal stop order with arrival times, distance and duration.

https://app.otiggo.com/api/v1/optimize

Billing

1 stop credit per stop in the request (not per kilometer)
2–200 stops per call in production
Failed optimizations are refunded automatically

Request body

Param	Type	Description
`start`required	Location	Departure point. Coordinates or street + postalCode + city.
`end`optional	Location	Optional return point. Same shape as start.
`stops`required	Stop[]	Array of stops (2–200). Each needs a unique id and a location.
`departureTime`optional	string (ISO 8601)	Optional departure datetime used for the schedule.
`avoidTolls`optional	boolean	When true, prefer routes without tolls.

Location

Either coordinates, or a full address (geocoded server-side — live keys only).

Param	Type	Description
`latitude`optional	number	−90 … 90
`longitude`optional	number	−180 … 180
`street`optional	string	Street address
`postalCode`optional	string	Postal code
`city`optional	string	City

Stop

Param	Type	Description
`id`required	string	Unique id (max 100 chars). Returned in order and schedule.
`deadline`optional	string	Optional "HH:MM" deadline in Europe/Paris time.
`serviceSeconds`optional	number	Optional time spent at the stop (0–3600).

Response fields

Param	Type	Description
`order`optional	string[]	Optimal stop ids in visit order.
`waypoints`optional	object[]	id, order, latitude, longitude for each stop.
`totalDistanceKm`optional	number	Total route distance.
`estimatedTimeMin`optional	number	Estimated duration in minutes.
`schedule`optional	object[]	Arrival times per stop (colisId, arrivee).
`departAt / returnAt`optional	string \| null	ISO departure and return times.
`lateStops`optional	object[] \| null	Stops past their deadline, if any.
`stopsCharged`optional	number	Credits charged (0 in sandbox).
`stopsBalance`optional	number	Remaining balance (live only).

Request

curl https://app.otiggo.com/api/v1/optimize \
  -H "Authorization: Bearer otg_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "start": { "street": "12 rue de la Paix", "postalCode": "75002", "city": "Paris" },
  "end": { "latitude": 48.8566, "longitude": 2.3522 },
  "departureTime": "2026-10-20T07:30:00+02:00",
  "avoidTolls": true,
  "stops": [
    { "id": "A", "latitude": 48.87, "longitude": 2.30, "deadline": "10:30", "serviceSeconds": 120 },
    { "id": "B", "street": "5 avenue Foch", "postalCode": "75116", "city": "Paris" }
  ]
}'

Response

200

{
  "order": ["B", "A"],
  "waypoints": [
    { "id": "B", "order": 1, "latitude": 48.8738, "longitude": 2.2950 },
    { "id": "A", "order": 2, "latitude": 48.8700, "longitude": 2.3000 }
  ],
  "totalDistanceKm": 7.4,
  "estimatedTimeMin": 38,
  "schedule": [
    { "colisId": "B", "arrivee": "2026-10-20T05:41:00Z" },
    { "colisId": "A", "arrivee": "2026-10-20T05:55:00Z" }
  ],
  "departAt": "2026-10-20T05:30:00Z",
  "returnAt": "2026-10-20T06:08:00Z",
  "lateStops": null,
  "stopsCharged": 2,
  "stopsBalance": 1998
}

PreviousAuthentication NextBalance