Hand this to your coding agent

WayMatrix — integration brief for a coding agent.
Everything below is generated from the API's own description. Follow it exactly;
do not infer endpoints, parameters or behaviour that is not listed here.

BASE URL
--------

  https://api.waymatrix.io

AUTHENTICATION
--------------

  Send the API key raw in the "Authorization" header.
  There is NO "Bearer " prefix. This is deliberate — it matches the
  openrouteservice client libraries, so their code works unchanged.
  A "Bearer " prefix is tolerated if you already send one.
  On GET requests you may pass ?api_key=<key> instead.

ENDPOINTS — this is all of them
-------------------------------

  POST  /v2/matrix/driving-car             Travel-time and distance matrix
  POST  /v2/matrix/driving-car/json        Travel-time and distance matrix (explicit JSON form)
  GET   /v2/directions/driving-car         Route between two points
  POST  /v2/directions/driving-car         Route with full options
  POST  /v2/directions/driving-car/json    Route, JSON form
  POST  /v2/directions/driving-car/geojson Route, GeoJSON form
  POST  /v2/directions/driving-car/gpx     Route, GPX form
  POST  /v2/isochrones/driving-car         Reachability polygons
  POST  /v2/isochrones/driving-car/geojson Reachability polygons (explicit GeoJSON form)
  GET   /v2/health                         Liveness
  HEAD  /v2/health                         Liveness, headers only
  GET   /v2/status                         Engine and graph provenance
  HEAD  /v2/status                         Engine and graph provenance, headers only

  CAUTION, python + gpx: The Python client calls response.json() unconditionally in every released version, so a GPX body raises "HTTP Error: 200". The fix exists upstream but has never been released. It fails the same way against the API we are compatible with, so it is not a difference between us — but a reader would reasonably conclude it was our fault. Show GPX with curl or plain HTTP instead.

WHAT THIS API DOES NOT HAVE — do not attempt these
--------------------------------------------------

  - No geocoding and no place search. Send longitude and latitude.
  - No live traffic. Durations come from the road network, not from current conditions.
  - Nothing outside North America, and no profile except driving.
  - No route optimization. Sequencing stops is a different problem and we do not solve it.

LIMITS
------

  The largest request THE SERVICE accepts is 90,000 elements
  (a 300 x 300 square matrix). YOUR tier's cap may be lower, and the
  per-tier figure below is the one that applies to your key. Split larger
  jobs into several requests; chunking costs exactly the same.
  Beta           60 requests/min, no monthly ceiling, 90,000 per request (300 x 300)
  Free           5 requests/min, 250,000 elements/month, 2,500 per request (50 x 50)
  Starter        120 requests/min, 5,000,000 elements/month, 90,000 per request (300 x 300)
  Growth         300 requests/min, 25,000,000 elements/month, 90,000 per request (300 x 300)
  Scale          600 requests/min, 100,000,000 elements/month, 90,000 per request (300 x 300)

BILLING
-------

  The billed unit is the element: one origin paired with one destination.
  A 200 x 150 matrix costs 30,000 of them whether sent as one request or thirty.
  These stop at the allowance rather than billing: Beta, Free, Starter.
  Requests that fail are not charged.

ERRORS — write retry logic against these, not against assumptions
-----------------------------------------------------------------

  401  No key at all
       {"error":"Authorization field missing","code":5001}
  403  Key present but rejected
       {"error":"Access to this API has been disallowed","code":5002}
  429  Rate limited
       {"error":"Rate Limit Exceeded","code":5003}
  403  Monthly quota exhausted
       {"error":"Quota exceeded","code":5004}
  400  Request larger than your tier allows
       {"error":{"code":6004,"message":"…Only a total of N routes are allowed."}}
  502  Routing engine unreachable
       {"error":"The routing engine is unavailable","code":5008}
  404  A path we do not serve
       {"error":"Not found","code":5010}

  IMPORTANT: this API never returns 503. An unreachable engine is 502.

  BRANCH RETRIES ON THE STATUS, NOT ON THE CODE.
  429 is always worth retrying with exponential backoff and jitter. It is
  either a per-minute rate limit or a concurrency refusal, and both clear
  on their own. Do not inspect the code to decide — that is how you miss
  one of them.
  403 is terminal. Never retry it. A monthly allowance is deliberately a
  403 rather than a 429, because it does not clear until the month does;
  a client that backed off and retried would hammer a wall for weeks.

  Read the code to decide WHAT TO SAY, never whether to retry. More than
  one rejection shares a status in both directions, and new codes may be
  added within the range. Code that branches on the status keeps working
  when they are; code that branches on the code does not.
  (Read off the running service on 2026-09-04.)

EXAMPLE REQUEST
---------------

  curl -X POST \
    https://api.waymatrix.io/v2/matrix/driving-car \
    -H "Authorization: $API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "locations": [
        [-87.6298, 41.8781],
        [-87.6244, 41.8796],
        [-87.6722, 41.9227]
      ],
      "metrics": ["duration", "distance"],
      "units": "km"
    }'

ATTRIBUTION — a licence condition on the application you build
--------------------------------------------------------------

  The map data is licensed under the Open Database License.
  If your application shows these results to people, it must credit
  "© OpenStreetMap contributors",
  linking https://www.openstreetmap.org/copyright.
  This is a legal requirement, not a preference. Include it.