Travel and places · OpenRouteService (OSRM fallback in dev)

navigation.route

Computes a route (driving, walking or cycling) between an origin and destination with optional waypoints. Each route is a record; details returns turn-by-turn steps.

Operation: POST /v1/capabilities/navigation.route/execute
operationId: executeNavigationRoute
Typical credits: 0
Search deadline: 15 s server-side
Paging: single result
Availability: UnavailableChecked 2026-09-23 21:02 UTC

Cost basis: Free tier. Availability is reported per deployment by GET /v1/catalog (available). The timestamped snapshot describes configuration, not provider uptime or your account's enabled choices. Check the catalog with your own key before a call. Credits are explained under credits and limits.

Request

Body of POST /v1/capabilities/navigation.route/execute, JSON, validated against the NavigationRouteRequest component of the public OpenAPI document. Defaults are applied server-side, so an omitted optional field behaves exactly as its default.

Request fields of navigation.route
Field	Type	Required	Default	Constraints and description
origin	string \| object	yes
origin.latwhen option 2	number	yes		min -90, max 90
origin.lonwhen option 2	number	yes		min -180, max 180
destination	string \| object	yes
destination.latwhen option 2	number	yes		min -90, max 90
destination.lonwhen option 2	number	yes		min -180, max 180
waypoints	string \| object[]	no		max items 10
mode	"driving" \| "walking" \| "cycling"	no
alternatives	boolean	no	false

Unknown keys are rejected with 400 invalid_request.

Rules the schema cannot express

Checked after schema validation; violations return 400 invalid_request with a plain message.

Origin and destination must geocode; an unresolvable place is refused.

Examples

Drive

curl

curl -s -X POST https://api.powerups-ai.store/v1/capabilities/navigation.route/execute \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"origin":"Berlin","destination":"Potsdam","mode":"driving"}'

Walk with alternatives

curl

curl -s -X POST https://api.powerups-ai.store/v1/capabilities/navigation.route/execute \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"origin":{"lat":51.5007,"lon":-0.1246},"destination":"British Museum","mode":"walking","alternatives":true}'

No recorded response is published for this capability yet. The envelope is the ExecuteResponse component (see sessions and records); the record keys below are what the adapter emits. A first call with the example above returns search_id, the records and the charge.

Result record

Every item in results[] carries record_id and title (contract, always present) and usually url and snippet. The keys below are the documented tier: produced deterministically by this capability, omitted when the source has no value, checked against recorded source fixtures in our test suite, and published as the NavigationRouteRecord component (all optional, extra keys allowed) so generated clients type them. The wire schema itself still validates only the base keys. See stability tiers.

Record keys of navigation.route
Key	Type	Presence
distance_km	number	always
duration_min	number	always
steps	integer	always
via	string[]	when the source has it
engine	string	always
attribution	string	always
license	string	always
license_url	string	always

Caveats

Details are served from the record stored at search time without a provider call. When that stored detail is no longer available the call returns 410 session_expired ("the cached record detail is no longer available. Run the search again."); it is never re-fetched.
When the OSRM demo engine is used (no OpenRouteService key in the deployment) notes[] says so: car profile only, no SLA.

Follow-ups

Paging: Single result; more is refused with 400 invalid_request.
Update: not offered.
Record actions:
- details: Turn-by-turn steps with distances.
Detail behaviour: Free provider lookup on first call; repeats are cached. details returns turn-by-turn steps from the stored route; no provider call.

record action

curl -s -X POST https://api.powerups-ai.store/v1/follow-up \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"record_id":"rec_…","action":"details"}'

`details` detail keys (owned, documented tier)

Turn-by-turn steps of the stored route; attribution trio only with OpenRouteService. Built entirely by our code and published as the NavigationRouteDetailsDetail component; the wire contract of detail stays untyped, extra keys may appear.

Detail keys of navigation.route details
Field	Type	Required
distance_km	number	yes
duration_min	number	yes
steps	object[]	yes
steps[].instruction	string	yes
steps[].distance_m	number	yes
steps[].duration_s	number	yes
steps[].name	string	no
attribution	string	no
license	string	no
license_url	string	no

Other record detail objects are provider-shaped: documented by observation, not by schema. Full follow-up semantics: follow-up.

Typed client

With types generated from the public document (see types, client and samples) the call is path-keyed and the body is checked at compile time:

TypeScript (openapi-fetch)

const { data, error } = await client.POST("/v1/capabilities/navigation.route/execute", {
  body: {
    "origin": "Berlin",
    "destination": "Potsdam",
    "mode": "driving"
  },
});
if (error) throw new Error(`${error.error.code}: ${error.error.message}`);
for (const record of data.results) console.log(record.record_id, record.title);