Retrieve an optimization

A call to this endpoint retrieves a duration-optimized route between input coordinates.

byMapbox (Maps)

800+calls

N/Alatency

Updated: Oct 27, 2026, 12:40 AM

Continue setup in your AI

Only public catalog IDs and a safe return path are handed to the Plugins page. This does not run the tool or confirm current availability, authorization, price, limits, or upstream status; those conditions are checked again before execution.

Selected tool: mapbox.optimized-trips.retrieve.v1
Provider scope: Mapbox (Maps)
Catalog updated: 2026-10-27T00:40:01.989419+00:00
Business task: Pending verification

Continue setupYou can return to this tool page if the selection is incomplete or expires.

Run on this page: Execute is the in-site test path. Continue setup is for adding the public selection to an external AI; the two paths are tracked and validated separately.

Discover -> Inspect -> Call

Call setup

Tool IDmapbox.optimized-trips.retrieve.v1

Request parametersJSON

Before this Call

1 credit / call

The final charge is settled from actual provider usage and will appear in Usage.

Field reference

profilestringOptional

A Mapbox Directions profile.

coordinatesstringOptional

{longitude},{latitude} coordinates. There must be between two and 12 coordinates.

annotationsstringOptional

Return additional metadata along the route. You can include several annotations as a comma-separated list. Must be used in combination with overview=full.

approachesstringOptional

A semicolon-separated list indicating the side of the road from which to approach waypoints in a requested route. Accepts unrestricted (default, route can arrive at the waypoint from either side of the road) or curb (route will arrive at the waypoint on the driving_side of the region). If provided, the number of approaches must be the same as the number of waypoints. But, you can skip a coordinate and show its position in the list with the ; separator. Must be used in combination with steps=true.

bearingsstringOptional

Influences the direction in which a route starts from a waypoint. Used to filter the road segment on which a waypoint will be placed by direction. This is useful for making sure the new routes of rerouted vehicles continue traveling in their current direction. A request that does this would provide bearing and radius values for the first waypoint and leave the remaining values empty. Must be used in combination with the radiuses parameter. Takes 2 values per waypoint: an angle clockwise from true north between 0 and 360, and the range of degrees by which the angle can deviate (recommended value is 45° or 90°), formatted as {angle, degrees}. If provided, the list of bearings must be the same length as the list of waypoints. But, you can skip a coordinate and show its position in the list with the ; separator.

destinationstringOptional

Specify the destination coordinate of the returned route. Accepts any (default) or last.

distributionsstringOptional

Specify pick-up and drop-off locations for a trip by providing a ; delimited list of number pairs that correspond with the coordinates list. The first number of a pair indicates the index to the coordinate of the pick-up location in the coordinates list, and the second number indicates the index to the coordinate of the drop-off location in the coordinates list. Each pair must contain exactly 2 numbers, which cannot be the same. The returned solution will visit pick-up locations before visiting drop-off locations. The first location can only be a pick-up location, not a drop-off location.

geometriesstringOptional

The format of the returned geometry. Allowed values are: geojson (as polyline

languagestringOptional

The language of returned turn-by-turn text instructions. See en (English).

overviewstringOptional

full (the most detailed geometry available), simplified (default, a simplified version of the full geometry), or false (no overview geometry).

radiusesstringOptional

; . Values can be any number greater than 0 or the string unlimited . A NoSegment error is returned if no routable road is located within the radius.

sourcestringOptional

any (default) or first .

stepsbooleanOptional

) or not (false , default).

roundtripbooleanOptional

true , default) or not (false ). If roundtrip=false , the source and destination parameters are required but not all combinations will be possible. See the Fixing start and end points section below for additional notes.

Continue setup in your AI

Selected tool

mapbox.optimized-trips.retrieve.v1

Provider scope

Mapbox (Maps)

Catalog updated

2026-10-27T00:40:01.989419+00:00

Business task

Pending verification

Continue setupYou can return to this tool page if the selection is incomplete or expires.