@uzmaps/api

HTTP client for the UzMap platform — search, geocoding, places, routing, distance matrix and isochrones for Uzbekistan, built from OpenStreetMap and other openly licensed data.

No dependencies. Works in the browser, in Node, and in any runtime with fetch.

npm install @uzmaps/api

Getting a key

Every call needs an API key. Create one in the UzMap console, then decide where it lives:

• In a browser, a key is public — it ships inside your page. Restrict it to your own origins; that restriction, not the key string, is what makes it safe.
• On a server, an unrestricted key can be kept secret. Keep it in an environment variable.

Usage

import { UzMapClient } from '@uzmaps/api';

const api = new UzMapClient({
  baseUrl: 'https://uzmaps.ndc.uz',
  apiKey: process.env.UZMAPS_KEY,
  language: 'uz', // 'uz' | 'ru' | 'en'
});

Search and geocoding

const { results } = await api.search('Chilonzor');
const { results: hits } = await api.autocomplete('chil');       // as-you-type
const place = await api.reverse(41.2995, 69.2401);               // coordinates → address
const near = await api.nearby(41.2995, 69.2401, { radius: 500, category: 'cafe' });
const detail = await api.place(results[0].id);

Routing

const { routes } = await api.route({
  points: [[69.2401, 41.2995], [69.2870, 41.3131]], // [lon, lat]
  mode: 'car',            // car | foot | bike | taxi | truck | motorcycle | bus
  alternatives: 2,
});
console.log(routes[0].distance, routes[0].duration); // metres, seconds

Distance matrix

Travel cost between every source and every target — the primitive behind "which courier is closest" and "order these stops sensibly".

const m = await api.matrix({
  points: [[69.24, 41.29], [69.28, 41.31], [69.22, 41.33]], // symmetric: everything to everything
  mode: 'car',
});
m.rows[0][2].distance; // metres, or null when no path exists
m.rows[0][2].duration; // seconds

Use sources and targets instead of points when the two sets differ. A request is capped at 2,500 pairs (sources × targets).

Isochrones

The area reachable within a travel time or distance, as GeoJSON you can hand straight to a map.

const iso = await api.isochrone({
  point: [69.2401, 41.2995],
  minutes: [5, 10, 15],   // or metres: [1000, 2000]
  polygons: true,         // filled areas; false gives lines
});
// iso.features[n].properties.contour_minutes

Units and conventions

• Distances are metres, durations are seconds, everywhere.
• Coordinates are [lon, lat], matching GeoJSON — note the order.
• null distance or duration in a matrix means no route exists, which is an answer rather than an error.

Errors

Failures throw UzMapApiError with a status and a message from the server.

import { UzMapApiError } from '@uzmaps/api';

try {
  await api.search('...');
} catch (e) {
  if (e instanceof UzMapApiError && e.status === 403) {
    // key is disabled, or this origin is not on its allowlist
  }
}

| status | meaning | |--------|---------| | 401 | no key sent, or the key is unknown | | 403 | key disabled, or the request's origin is not allowed | | 429 | rate limit exceeded |

Related

• @uzmaps/engine — the interactive map
• @uzmaps/ui — React components

Licence

MIT. Map data © OpenStreetMap contributors (ODbL) and © Overture Maps Foundation.