# WayMatrix > The routing API your client library already knows how to call. 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= 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 rejected, or the monthly quota is spent {"error":"Access to this API has been disallowed","code":5002} 429 Rate limited {"error":"Rate Limit Exceeded","code":5003} 502 Routing engine unreachable {"error":"The routing engine is unavailable","code":5008} 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. 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. PROMPTS FOR A CODING AGENT -------------------------- Each is self-contained and generated from this API description: https://www.waymatrix.io/agents/prompts first-call Start here. Sets up the credential and proves the connection with one request. big-matrix Your origin and destination lists multiply out past your tier's per-request cap. directions You need the path, distance and duration for one journey rather than a grid. isochrones Coverage questions: what is inside a 30-minute drive of this depot. migrate-ors You already call openrouteservice and want the same code pointed here. migrate-google You call Google computeRouteMatrix. This is a rewrite, not a URL change. errors Before you ship. Retrying the wrong status is how a quota outage becomes an outage. cost Before you commit. Turns a description of your job into a number. PAGES WORTH READING ------------------- https://www.waymatrix.io/agents this brief, rendered for a person https://www.waymatrix.io/agents/prompts copy-paste prompts, one per task https://www.waymatrix.io/guides/from-openrouteservice moving an existing openrouteservice integration https://www.waymatrix.io/guides/from-google-distance-matrix field by field from Google Distance Matrix https://www.waymatrix.io/pricing what a workload costs https://www.waymatrix.io/how-the-graph-is-built the map data, its licence, and how the graph was built