Routing

Three endpoints cover travel: /api/route returns turn-by-turn routes between two or more points, /api/matrix returns travel cost between every source and every target, and /api/isochrone returns the area reachable from a point within a time or distance budget. All three are served by a Valhalla engine behind the Go API server; the server translates between the UzMap vocabulary described here and Valhalla's own, so you never see Valhalla's field names, costing names or units.

Conventions shared by all three endpoints#

Two consequences of the above are easy to miss:

• X-API-Key is not in the CORS allow-list, so a cross-origin browser request that sets that header is blocked by the browser at preflight. From browser code, pass ?key= instead.
• Query-string points that fail to parse as lon,lat are dropped silently, not rejected. A typo in one point therefore shows up as "at least two points required" or as a matrix with fewer rows than you sent, rather than as a parse error.

Why two request forms: GET is what a browser address bar or a curl one-liner reaches for; POST is what survives a large point list. A 50×50 matrix carries 100 coordinates, which is exactly the case a URL cannot hold (matrix.go, file comment).

Travel modes#

mode is accepted by all three endpoints. The server maps it to a Valhalla costing model; an unknown or empty mode falls back to car, and the response echoes the mode it actually used.

The avoidance flags only change the costing options of the motor modes. For foot the adapter sends a fixed walking_speed of 5.0; for bike it sends a Hybrid bicycle type with use_roads set to 0.4. Sending avoid_tolls=1 with mode=foot is accepted and does nothing.

Costing options the adapter sends, for reference:

/api/route#

Returns one recommended route and up to three alternatives between two or more points.

Request#

The GET and POST forms do not accept the same set of fields. Note in particular that the language parameter is lang on GET but language on POST, and that shortest and heading exist only on POST.

The adapter has AvoidFerries, DepartAt and per-waypoint Name fields, but neither handler populates them, so ferries cannot be avoided and a departure time cannot be set over HTTP.

The handler gives the engine 25 seconds; the engine client has its own 25-second timeout as well.

Response#

{
  "routes": [
    {
      "id": "route-0",
      "mode": "car",
      "distance": 6094,
      "duration": 419,
      "geometry": [[69.2401, 41.2995], [69.2405, 41.2998]],
      "bbox": [69.2401, 41.2995, 69.2870, 41.3131],
      "legs": [
        {
          "distance": 6094,
          "duration": 419,
          "steps": [
            {
              "type": "depart",
              "modifier": "",
              "instruction": "Bunyodkor shoh ko‘chasi bo‘ylab yo‘lga chiqing",
              "verbal": "Bunyodkor shoh ko‘chasi bo‘ylab yo‘lga chiqing",
              "street_names": ["Bunyodkor shoh ko‘chasi"],
              "distance": 320,
              "duration": 41,
              "geometry_start": 0,
              "geometry_end": 7
            },
            {
              "type": "arrive",
              "modifier": "right",
              "instruction": "Manzilga yetib keldingiz, u o‘ng tomonda",
              "verbal": "Manzilga yetib keldingiz, u o‘ng tomonda",
              "distance": 0,
              "duration": 0,
              "geometry_start": 41,
              "geometry_end": 41
            }
          ]
        }
      ],
      "summary": "Bunyodkor shoh ko‘chasi · Kichik halqa yo‘li",
      "has_highway": true,
      "recommended": true
    }
  ],
  "language": "uz",
  "engine": "valhalla"
}

(Abridged: a real geometry array has one entry per shape point, and a real steps array has one entry per manoeuvre.)

Top level:

Route:

Leg (Leg):

Step (Step):

Sign (Sign):

Manoeuvre types#

The engine's numeric manoeuvre types are normalised to a type and modifier pair by the maneuverMap table in routing/valhalla.go.

An engine type outside this table produces an empty type and modifier.

Languages#

Examples#

Recommended route plus one alternative, Russian instructions:

curl -H "X-API-Key: $KEY" \
  "https://uzmaps.ndc.uz/api/route?points=69.2401,41.2995|69.2870,41.3131&mode=car&lang=ru&alternatives=1"

Walking route with Uzbek instructions, via POST:

curl -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"points":[[69.2401,41.2995],[69.2870,41.3131]],"mode":"foot","language":"uz"}' \
  https://uzmaps.ndc.uz/api/route

Shortest driving route avoiding tolls, with the car's current heading (POST-only fields):

curl -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"points":[[69.2401,41.2995],[69.2870,41.3131]],"mode":"car","shortest":true,"avoid_tolls":true,"heading":90,"alternatives":2}' \
  https://uzmaps.ndc.uz/api/route

/api/matrix#

Returns distance and duration for every source–target pair in one call. A matrix is costed with the same avoidance options as a route (avoid_tolls, avoid_highways, shortest), so that the target you pick from a matrix is the one the route you draw afterwards actually goes to (routing/matrix.go, MatrixRequest comment). The one difference is use_ferry, which the route adapter sends and the matrix adapter does not.

Request#

There is no language parameter: a matrix has no instructions.

Size limit. sources × targets must not exceed 2500. The cap is on the product, not on either side, so 1×2500 and 50×50 both fit and 51×50 does not. A request over the cap is rejected with 400 before anything reaches the engine. The reason for a cap: the engine computes a matrix by expanding the graph from every source, so cost grows with the product, and an uncapped endpoint would let one key saturate the engine for everyone (routing/matrix.go, MaxMatrixPairs comment).

The handler allows 60 seconds because a full matrix is many graph expansions; the engine client's own 25-second timeout still applies.

Response#

{
  "mode": "car",
  "sources": 1,
  "targets": 2,
  "cells": [
    {"source": 0, "target": 0, "distance": 6094, "duration": 419},
    {"source": 0, "target": 1, "distance": 6695, "duration": 519}
  ],
  "engine": "valhalla",
  "rows": [
    [
      {"source": 0, "target": 0, "distance": 6094, "duration": 419},
      {"source": 0, "target": 1, "distance": 6695, "duration": 519}
    ]
  ]
}

Cell:

A null distance or duration means no path exists between that pair — an island, a gated area, a point the network cannot reach in the requested mode. It is a real answer, not an error: the rest of the matrix is returned as normal, because a single unreachable pair must not fail the whole request (routing/matrix.go, MatrixCell comment; TestMatrixKeepsUnreachablePairsAsNull in routing/matrix_test.go). The engine reports matrix distance in kilometres; the server multiplies by 1000 so this endpoint agrees with the rest of the API (TestMatrixConvertsKilometresToMetres).

Examples#

One source to two targets:

curl -H "X-API-Key: $KEY" \
  "https://uzmaps.ndc.uz/api/matrix?sources=69.2401,41.2995&targets=69.2870,41.3131|69.22,41.33&mode=car"

Symmetric matrix from a browser (query-string key, because the X-API-Key header is not CORS-allowed):

const res = await fetch('https://uzmaps.ndc.uz/api/matrix?key=' + encodeURIComponent(KEY), {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    points: [[69.2401, 41.2995], [69.2870, 41.3131], [69.22, 41.33]],
    mode: 'car',
    avoid_tolls: true,
  }),
});
const matrix = await res.json();
const unreachable = matrix.cells.filter((c) => c.distance === null);

/api/isochrone#

Returns the area reachable from one point within one or more time or distance budgets, as a GeoJSON FeatureCollection with one feature per contour. It is raw GeoJSON rather than a bespoke schema because every mapping client can already draw it (routing/matrix.go, IsochroneResponse comment).

Request#

The two forms default polygons differently: GET defaults to polygons because a bare browser request wants something it can fill and hit-test, and lines are the specialised choice (matrix.go, handleIsochrone comment); POST defaults to false because that is the JSON zero value. Set it explicitly in POST bodies. Lines are cheaper and suit a heat-style overlay; polygons suit a "can we deliver here" hit test (routing/matrix.go, IsochroneRequest comment).

DepartAt exists in the adapter but is not populated by the handler, so a departure time cannot be set over HTTP.

Contour rules#

The six-contour cap exists because each contour is a separate expansion of the graph, so it is the same protection the 2500-pair cap gives the matrix (routing/matrix.go, MaxIsochroneIntervals comment). The non-positive check is made in the adapter rather than the handler, which is why it surfaces as 502 rather than 400.

Distance contours are given in metres and converted to kilometres for the engine on the way in, and back to metres on the way out.

Response#

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {"contour": 5, "metric": "time", "fill": "#bf4040", "contour_minutes": 5},
      "geometry": {
        "type": "Polygon",
        "coordinates": [[[69.24, 41.30], [69.25, 41.30], [69.25, 41.31], [69.24, 41.30]]]
      }
    }
  ],
  "mode": "car",
  "engine": "valhalla"
}

Each feature's properties carries the engine's own metadata plus one field the server adds:

Read contour_minutes or contour_metres rather than contour, so you never need to know which unit the engine was given. The server decides which one to add from the feature's own metric property, so the label stays correct even if the engine reorders, merges or drops contours; only when a feature carries no recognisable metric does it fall back to whichever axis the request used. A time contour is never also labelled in metres.

If the engine returns no features, the request fails with 502 no reachable area found.

Examples#

Walking reach in 5, 10 and 15 minutes (GET, so polygons by default):

curl -H "X-API-Key: $KEY" \
  "https://uzmaps.ndc.uz/api/isochrone?point=69.2401,41.2995&mode=foot&minutes=5,10,15"

Driving distance rings as lines, with small islands removed (POST, so polygons must be stated):

curl -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"point":[69.2401,41.2995],"mode":"car","metres":[1000,2000,5000],"polygons":false,"denoise":0.5}' \
  https://uzmaps.ndc.uz/api/isochrone

Drawing the result with MapLibre GL, which accepts the response as a GeoJSON source directly:

const res = await fetch('https://uzmaps.ndc.uz/api/isochrone?key=' + encodeURIComponent(KEY), {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ point: [69.2401, 41.2995], mode: 'car', minutes: [10, 20], polygons: true }),
});
const isochrone = await res.json();
map.addSource('reach', { type: 'geojson', data: isochrone });
map.addLayer({
  id: 'reach-fill',
  type: 'fill',
  source: 'reach',
  paint: { 'fill-color': ['get', 'fill'], 'fill-opacity': 0.25 },
});

Errors#

Every error is {"error": "<message>"}, except key errors, which the gate writes as {"error", "code", "message", "docs"}.