Copy page

Getting started

Getting started

Getting started

A routing API compatible with openrouteservice, for three endpoint families: matrix, directions and isochrones. If you already use an openrouteservice client, point it at this base URL and change the key. Nothing else changes.

Authentication

Send your key raw in the Authorization header, with no Bearer prefix:

Code
curl -X POST https://api.waymatrix.io/v2/matrix/driving-car \
  -H 'Authorization: YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"locations": [[-87.6298, 41.8781], [-87.6244, 41.8796]]}'

That is deliberately the shape openrouteservice's own client libraries send, so an existing client needs no change. api_key as a query parameter works too, though a key in a URL ends up in browser history and proxy logs — prefer the header wherever you control the request.

What this service is, honestly

Read this before integrating. Every item is a real constraint, not a disclaimer.

• driving-car only. Any other profile returns the engine's own "incorrect value" error. Truck, bike and foot profiles are not served.
• North America only, from an OpenStreetMap extract. Excellent in metros, variable in rural areas.
• No live traffic. Travel times are free-flow estimates from the road graph. If your product needs minute-accurate ETAs in congestion, this is the wrong tool and we would rather you knew now.
• Bring your own coordinates. There is no geocoding endpoint.

What a request costs

Metering is per element, not per request.

• A matrix costs |sources| × |destinations| elements. Omitting sources or destinations selects every location, so an n-location request with neither field costs n².
• Directions and isochrones cost a flat number of elements per call.

Failed calls are never charged. Usage is counted on success only, and a request refused for being over your plan's per-request limit costs nothing at all — it is rejected before the routing engine is touched.

Worth knowing if you are migrating: openrouteservice meters per request, so your existing quota arithmetic does not carry over. A 1×150 matrix decrements their quota by one and costs 150 elements here.

Attribution

Routing data is © OpenStreetMap contributors, available under the Open Database Licence.

Every response carries the engine's metadata.attribution field. Do not strip it. If your application publicly displays results, or maps built from them, you must credit OpenStreetMap — this is a licence obligation that passes through to you, not a preference of ours.

Errors

Two shapes, matching openrouteservice, because they come from two places.

The routing engine returns a numeric code:

Code
{ "error": { "code": 6004, "message": "Request parameters exceed the server configuration limits." } }

The gateway — authentication, rate limits, quota — returns a plain string:

Code
{ "error": "Rate Limit Exceeded", "code": 5003 }

Read error as a string for the second and as an object for the first, exactly as you would against openrouteservice today. The numeric code alongside the string is ours and additive.

Rate limiting is 429 and is transient — back off and retry, which openrouteservice's client libraries do automatically. Quota exhaustion is 403 and is terminal until the quota resets.