HTTP API

Everything the map does, it does over this API. There is no privileged internal channel — the JavaScript client is an ordinary consumer of the same endpoints, so anything the map can do, your server can do too.

Base URL#

https://uzmaps.ndc.uz

One origin serves the API, the tiles and the browser SDK. There is no separate API host, and therefore no CORS origin to configure for the map itself.

Authentication#

Every request needs an API key, presented one of two ways.

curl -H "X-API-Key: $KEY" "https://uzmaps.ndc.uz/api/search?q=Chilonzor"

Two endpoints are deliberately open and need no key: /health and /api/status. Uptime checks and the client's own capability probe work without credentials, and the browser SDK at /v1/ is served unauthenticated because a script has to load before it can present anything.

See API keys and quotas for origin restrictions, rate limits and monthly allowances.

Conventions#

Coordinates are [longitude, latitude] — GeoJSON order. Where an endpoint takes a query string, the form is lon,lat.

Distances are metres, durations are seconds. Everywhere, without exception.

Times are ISO 8601 in UTC. Quota periods and usage buckets are aligned to the UTC calendar month, so an allowance and an invoice can never disagree about which month a request fell in.

null means "no answer exists", not "something went wrong". A matrix cell with a null distance means no route connects that pair; the surrounding cells are still valid.

Errors#

Failures return JSON with a machine-readable code and a sentence describing what to change.

{
  "code": 403,
  "error": "Forbidden",
  "message": "origin https://evil.example is not allowed for this API key",
  "docs": "https://uzmaps.ndc.uz/docs/api-keys"
}

Reference#