Create Routes

POST/routing/create

Generate optimized trips from a set of bookings. The engine clusters stops, sequences them optimally, and returns trips with route geometry. This endpoint is asynchronous - it returns a production ID to poll for results.

Request Body

Field	Type	Required	Description
`jobs`	Job[]	Yes	Array of bookings to route
`trips`	Trip[]	No	Existing trips to potentially join jobs to
`settings`	RoutingSettings	No	Routing configuration
`areas`	Area[]	No	Geographic zones for area-based rules
`attributes`	Attribute[]	No	Service attributes
`profiles`	Profile[]	No	Service profiles that can share rides
`locations`	Location[]	No	Known locations with custom stop times
`traffic`	TrafficSettings	No	Traffic adjustment settings

Job

Field	Type	Required	Description
`id`	string	Yes	Unique job identifier
`from`	Coordinates	Yes	Pickup location
`fromAddr`	string	No	Pickup address display name
`to`	Coordinates	Yes	Drop-off location
`toAddr`	string	No	Drop-off address display name
`pick`	ISO8601	Yes*	Requested pickup time
`drop`	ISO8601	Yes*	Requested drop-off time
`seats`	number	Yes	Number of seats required
`passenger`	string	No	Passenger name/identifier
`phone`	string	No	Contact phone number
`attr`	string[]	No	Required attributes (wheelchair, child_seat, etc.)
`unit`	string	No	Site/unit identifier for multi-tenant routing
`private`	boolean	No	If true, job cannot be shared with others
`forceJoin`	string	No	Group ID - jobs with same value must route together
`waitAndReturnId`	string	No	Links outbound and return legs
`profileName`	string	No	Service profile name

*Either pick or drop must be provided.

Coordinates

Field	Type	Required	Description
`lat`	number	Yes	Latitude
`lng`	number	Yes	Longitude

RoutingSettings

Setting	Type	Default	Description
`maxSinglePassengerTime`	RangeValue	60	Max passenger ride time (minutes)
`maxTripDuration`	RangeValue	120	Max total trip duration (minutes)
`maxTripStops`	number	10	Maximum stops per trip
`maxPickupStops`	number	-	Maximum pickup stops per trip
`maxDropoffStops`	number	-	Maximum drop-off stops per trip
`maxPassengers`	number	8	Maximum total passengers per trip
`maxPassengersAtOnce`	number	4	Max passengers at any point
`maxReservationsAtOnce`	number	4	Max jobs at any point
`sharedRideRatio`	number	1.5	Max shared-ride vs direct ratio
`sharedRideDifferenceLimit`	number	15	Max additional minutes vs direct
`maxBoardingDelay`	number	15	How late driver can arrive (minutes)
`maxBoardingEarly`	number	15	How early driver can arrive (minutes)
`maxDropOffDelay`	number	15	How late for drop-off (minutes)
`maxDropOffEarly`	number	15	How early for drop-off (minutes)
`tripBoardingTime`	number	120	Time to complete pickup (seconds)
`tripDropOffTime`	number	60	Time to complete drop-off (seconds)
`waitForBoardingTime`	boolean	false	Wait until exact pickup time
`onlyPrivate`	boolean	false	Disable all ride sharing
`isClusteringEnabled`	boolean	true	Enable stop clustering
`clusterReservationsRadius`	number	200	Cluster radius (meters)

RangeValue

For settings that vary by distance:

{
  "value": 60,
  "ranges": [
    { "from": 0, "to": 10000, "value": 45 },
    { "from": 10000, "to": 50000, "value": 60 }
  ]
}

Field	Type	Description
`value`	number	Default value
`ranges`	Range[]	Distance-based overrides
`ranges[].from`	number	Start distance (meters)
`ranges[].to`	number	End distance (meters)
`ranges[].value`	number	Value for this range

Example Response

{
  "productionId": "prod_xyz789",
  "status": "processing"
}

Poll the Get Route Result endpoint with the productionId to retrieve the optimized trips.

Request Body

Job

Coordinates

RoutingSettings

RangeValue

Example Response

On this page