AI Power Ups

Menu

Contents

Travel and places · OpenRouteService (OSRM fallback in dev)

navigation.matrix

Returns a duration and distance matrix between every pair of the given locations for the chosen mode. One record per call.
Operation
POST /v1/capabilities/navigation.matrix/execute
operationId
executeNavigationMatrix
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.matrix/execute, JSON, validated against the NavigationMatrixRequest 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.matrix
FieldTypeRequiredDefaultConstraints and description
locationsstring | object[]yesmin items 2, max items 25
mode"driving" | "walking" | "cycling"no
  • Unknown keys are rejected with 400 invalid_request.

Examples

Three cities

curl
curl -s -X POST https://api.powerups-ai.store/v1/capabilities/navigation.matrix/execute \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"locations":["Berlin","Potsdam","Leipzig"],"mode":"driving"}'
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 NavigationMatrixRecord 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.matrix
KeyTypePresenceNote
locationsstring[]always
durations_minnumber[][]always
distances_kmnumber[][]always
enginestringalways
attributionstringalways
licensestringalways
license_urlstringalways

Caveats

  • When the OSRM demo engine is used (no OpenRouteService key in the deployment) the envelope carries the same notes entry as navigation.route: car profile only, no SLA.

Follow-ups

  • Paging: Single result; more is refused with 400 invalid_request.
  • Update: not offered.
  • Record actions: none.
  • Detail behaviour: No record actions.

Record detail objects of this capability 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.matrix/execute", {
  body: {
    "locations": [
      "Berlin",
      "Potsdam",
      "Leipzig"
    ],
    "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);