Docs
Request an API key

How the API works

What happens to a request, and why the API can swap its engines without breaking your client.

/docs/concepts/how-it-works.md

One contract over interchangeable engines

Routing and geocoding are done by separate engines. /v2 puts one contract in front of them, so your client talks to the same request and response shapes whichever engines are running. GET /v2/info tells you which ones are.

What happens to a request

  1. The gateway checks your key and your rate limit. A missing or invalid key stops here with 401, and too many requests stop here with 429.
  2. The API validates the request against the published schemas. Anything invalid stops with a 400.
  3. An engine does the work. The API translates your request into that engine's format.
  4. The API shapes the reply into the contract, so units, field names and errors are the same every time.

What this means for your code

  • Write to the contract. Use the documented fields, not engine-specific behaviour. See API rules.
  • Expect some answers to differ between engines. The contract promises the shape, not identical routes or places.
  • Check what's offered. A capability appears in GET /v2/info only if its endpoint works here.

Data

Roads and places come from OpenStreetMap, as a snapshot rather than a live feed. See Coverage and data.