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.

Getting a key

Sign in, open Your API keys, and press Create API Key. You get a key on the free plan immediately, and it appears in the list on that page to copy and to roll.

You can hold more than one key at a time, so a replacement can be running before you retire the old one.

A new key expires after 30 days unless you set Expiration to Never. An expired key returns 403 (code 5002); the account is untouched, so your plan, your allowance and your usage all survive it and a new key works immediately.

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 the shape client libraries already 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 costs a flat number of elements per call (10 elements).
• Isochrones scale with reach: locations × 100 × (max_range / reference)² elements (reference is 300 s or 10 km).

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: this API meters per element, not per request, so quota arithmetic from a per-request API does not carry over. A 1×150 matrix is one request and 150 elements.

Attribution

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

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 license obligation that passes through to you, not a preference of ours.

Errors

Two shapes, 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. The numeric code alongside the string is ours and additive.

Rate limiting is 429 and is transient — back off and retry, which client libraries usually do for you. Quota exhaustion is 403 and is terminal until the quota resets.