# 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**:

```bash
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](https://www.openstreetmap.org/copyright).

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:

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

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

```json
{ "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.