Every endpoint is JSON over HTTP. Requests that carry coordinates are POSTs with a body — deliberately, because a query string is logged by every proxy in the path and kept for weeks. The three endpoints that have to work inside an HTML attribute (a tile, a static image, an embedded map) are GETs and say so.
The key you type is kept in this browser's local storage and sent only to this service. Every “Send request” button on this page issues a real call with it.
Three places, all equivalent. Use whichever your client makes easy.
Authorization: Bearer dgk_live_… # servers
X-API-Key: dgk_live_… # most SDKs
?key=dgk_live_… # tiles, static images, iframes — a browser
# will not attach a header to those
Branch on error, not on the status code: unroutable and
invalid_coordinate are both 422 and need opposite handling.
| Status | error | What it means | Retry? |
|---|---|---|---|
| 400 | invalid_request | The body did not parse, or a field has the wrong type | No |
| 401 | unauthorized | Missing, unknown, expired or disabled key | No |
| 403 | key_scope | This key may not call this family of services | No |
| 403 | referrer_not_allowed | This key is bound to specific web origins | No |
| 422 | invalid_coordinate | Out of range, or outside this deployment's map data | No |
| 422 | unroutable | These coordinates have no road answer. Tell the user. | No |
| 429 | rate_limited / quota_exceeded | Honour Retry-After | Yes, later |
| 501 | service_unavailable | This deployment does not run that backend. Check /v1/capabilities. | No |
| 503 | engine_unavailable | The routing engine could not be reached | Yes, shortly |
GET /v1/capabilities is unauthenticated and lists every service, whether it
is available, and what configuration would turn it on. Call it at startup and render the
product this instance supports rather than discovering a 501 in front of a user.
Every service is also served in the request and response shapes of the dominant
commercial maps platform, so an existing integration moves by changing a base URL. The
parameter names, the JSON keys and the status strings match; polylines are
re-encoded to precision 5 because that is what those client libraries decode.