@uzmaps/api client

npm install @uzmaps/api

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

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

status(): Promise<Status>

const s = await api.status();
if (!s.routing) console.warn('routing engine is not answering');
console.log(`${s.docs} places indexed, data built ${s.built_at}`);
if (s.sources?.terrain) console.log('terrain tiles available');

categories(): Promise<{ groups: CategoryGroupInfo[]; categories: CategoryInfo[] }>

const { groups, categories } = await api.categories();
const food = categories.filter((c) => c.group === 'food');
console.log(groups.length, 'groups;', food.map((c) => c.id));

search(query: string, options?: SearchOptions): Promise<SearchResponse>

const { results, intent, took_ms } = await api.search('dorixona', {
  near: { lat: 41.2995, lon: 69.2401 },
  limit: 5,
});
if (intent) console.log(`category browse: ${intent.label} (${intent.category})`);
for (const r of results) console.log(r.name, '—', r.label, r.lat, r.lon);
console.log(`${took_ms} ms`);

// Everything in the "food" group inside a viewport, nearest first
const inView = await api.search('', {
  category: 'group:food',
  near: { lat: 41.2995, lon: 69.2401 },
  bbox: [69.2, 41.27, 69.3, 41.33],
  limit: 40,
});

autocomplete(query: string, options?: SearchOptions): Promise<SearchResponse>

let pending: AbortController | undefined;

async function suggest(text: string) {
  pending?.abort();
  pending = new AbortController();
  const { results } = await api.autocomplete(text, { signal: pending.signal });
  return results.map((r) => r.name);
}

reverse(
  lat: number,
  lon: number,
  options?: { language?: Language; signal?: AbortSignal },
): Promise<ReverseResponse>

const r = await api.reverse(41.2995, 69.2401, { language: 'ru' });
console.log(r.short);              // "улица Амира Темура, 12"
console.log(r.label);              // full line
if (r.street) console.log(r.street.name);

nearby(
  lat: number,
  lon: number,
  options?: {
    radius?: number;        // metres; server default 500, capped at 20 000
    category?: string;      // e.g. 'food.cafe'
    kinds?: PlaceKind[];    // server default ['poi']
    limit?: number;         // server default 20
    language?: Language;
    signal?: AbortSignal;
  },
): Promise<{ results: SearchResult[] }>

const { results } = await api.nearby(41.2995, 69.2401, {
  radius: 800,
  category: 'food.cafe',
  limit: 10,
});
for (const r of results) console.log(r.name, Math.round(r.distance ?? 0), 'm');

lookup(
  lat: number,
  lon: number,
  name: string,
  options?: { radius?: number; language?: Language; signal?: AbortSignal },
): Promise<{ result: SearchResult | null }>

// From a map click: feature name and its lngLat
const { result } = await api.lookup(41.3111, 69.2797, 'Chorsu bozori');
if (result) {
  const details = await api.place(result.id);
  console.log(details.full_address);
}

place(id: number, options?: { language?: Language; signal?: AbortSignal }): Promise<PlaceDetails>

const details = await api.place(12345, { language: 'en' });
console.log(details.full_address);
if (details.details.open_status?.open) console.log('open now');
if (details.geometry_url) {
  const feature = await api.geometry(details.id);
  console.log(feature.geometry.type); // 'Polygon' | 'MultiPolygon' | 'MultiLineString'
}

placeByOsm(
  type: 'n' | 'w' | 'r',
  id: number,
  options?: { language?: Language; signal?: AbortSignal },
): Promise<PlaceDetails>

const tashkent = await api.placeByOsm('r', 2214960);
console.log(tashkent.name, tashkent.population);

geometry(id: number, signal?: AbortSignal): Promise<Feature>

const outline = await api.geometry(12345);
map.highlight.setGeometry(outline); // e.g. with @uzmaps/engine

districts(signal?: AbortSignal): Promise<FeatureCollection>

const { features } = await api.districts();
const mahallas = features.filter((f) => f.properties?.level === 10);
console.log(mahallas.length, 'mahallas');

photo(wikidata: string, signal?: AbortSignal): Promise<{ photo: Photo | null }>

photoUrl(photo: Photo): string

const img = document.querySelector<HTMLImageElement>('#photo')!;
const caption = document.querySelector<HTMLElement>('#caption')!;

const details = await api.place(12345);
const qid = details.details.wikidata;
if (typeof qid === 'string') {
  const { photo } = await api.photo(qid);
  if (photo) {
    img.src = api.photoUrl(photo);
    caption.textContent = photo.attribution;
  }
}

route(request: RouteRequest, signal?: AbortSignal): Promise<RouteResponse>

const { routes, warnings } = await api.route({
  points: [[69.2401, 41.2995], [69.2870, 41.3131]], // [lon, lat]
  mode: 'car',
  avoid_tolls: true,
});
const best = routes.find((r) => r.recommended) ?? routes[0];
console.log(best.summary, best.distance, 'm', best.duration, 's');
for (const step of best.legs[0].steps) console.log(step.instruction);
if (warnings?.length) console.warn(warnings);

matrix(request: MatrixRequest, signal?: AbortSignal): Promise<MatrixResponse>

const m = await api.matrix({
  sources: [[69.2401, 41.2995]],
  targets: [[69.2870, 41.3131], [69.2200, 41.3300], [69.3100, 41.2800]],
  mode: 'car',
});
const nearest = m.rows[0]
  .filter((c) => c.duration !== null)
  .sort((a, b) => a.duration! - b.duration!)[0];
console.log('closest target:', nearest.target, nearest.duration, 's');

isochrone(request: IsochroneRequest, signal?: AbortSignal): Promise<IsochroneResponse>

const iso = await api.isochrone({
  point: [69.2401, 41.2995],
  mode: 'foot',
  minutes: [5, 10, 15],
  polygons: true,
});
for (const f of iso.features) {
  console.log(f.properties?.contour_minutes, 'min:', f.geometry.type);
}

usage(options?: { days?: number; series?: boolean; signal?: AbortSignal }): Promise<UsageReport>

const report = await api.usage({ days: 7, series: true });
console.log(report.name, report.requests, 'requests,', report.denied, 'denied');
for (const p of report.products) console.log(p.product, p.requests);
if (report.quota) console.log(`${report.quota.remaining} left until ${report.quota.resets}`);

class UzMapApiError extends Error {
  constructor(public status: number, message: string);
  name: 'UzMapApiError';
}

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

try {
  await api.search('Chilonzor');
} catch (e) {
  if (e instanceof UzMapApiError) {
    if (e.status === 403) console.error('key disabled or origin not allowed');
    else console.error(e.status, e.message);
  } else {
    throw e; // network, timeout or abort
  }
}

formatDistance(metres: number, lang?: Language): string   // lang defaults to 'uz'
formatDuration(seconds: number, lang?: Language): string  // lang defaults to 'uz'

import { formatDistance, formatDuration } from '@uzmaps/api';

formatDistance(1234);        // '1.2 km'
formatDistance(1234, 'ru');  // '1.2 км'
formatDuration(4500, 'en');  // '1 h 15 min'

type Language = 'uz' | 'uz-Cyrl' | 'ru' | 'en';
type PlaceKind = 'place' | 'street' | 'poi' | 'address' | 'nature';

interface Address {
  street?: string;
  housenumber?: string;
  neighbourhood?: string;
  suburb?: string;
  city?: string;
  district?: string;
  region?: string;
  postcode?: string;
}

interface SearchResult {
  id: number;
  kind: PlaceKind;
  category: string;
  group: string;
  icon: string;
  name: string;
  label: string;           // secondary line, e.g. "Kafe · Amir Temur ko'chasi, 12, Toshkent"
  category_label: string;
  lat: number;
  lon: number;
  bbox: [number, number, number, number];
  distance?: number;       // metres from `near` / the nearby point, when one was given
  address: Address;
  names?: Record<string, string>;
  matched?: string[];
  rank: number;
  reason?: string;
}

interface SearchIntent { category: string; browse: boolean; label: string; icon: string }

interface SearchResponse {
  query: string;
  results: SearchResult[];
  took_ms: number;
  intent?: SearchIntent;
}

interface SearchOptions {
  near?: { lat: number; lon: number };
  bias?: number;
  limit?: number;
  kinds?: PlaceKind[];
  category?: string;
  bbox?: [number, number, number, number];
  language?: Language;
  signal?: AbortSignal;
}

interface OpenStatus {
  open: boolean;
  known: boolean;
  all_day?: boolean;
  next_change?: string;   // "HH:MM"
  closes_soon?: boolean;
  opens_soon?: boolean;
  next_day?: number;      // 0 = today, 1 = tomorrow, ...
}

interface HoursSchedule {
  raw: string;
  all_day: boolean;
  days: { open: number; close: number }[][];  // 7 days; minutes from midnight
  unparsed?: boolean;
}

interface PlaceDetails extends SearchResult {
  osm: { type: 'n' | 'w' | 'r'; id: number; url: string };
  tags: Record<string, string>;
  population?: number;
  admin_level?: number;
  full_address: string;
  details: {
    phone?: string;
    website?: string;
    instagram?: string;
    telegram?: string;
    email?: string;
    cuisine?: string;
    wheelchair?: string;
    opening_hours?: string;
    hours?: HoursSchedule;
    open_status?: OpenStatus;
    [k: string]: unknown;
  };
  photo_hint?: string;
  nearby: SearchResult[];
  geometry_url?: string;
}

interface Photo {
  url: string;          // server-relative; resolve with photoUrl()
  source_url: string;   // the Commons file page
  author?: string;
  license?: string;
  license_url?: string;
  title?: string;
  width?: number;
  height?: number;
  attribution: string;
}

interface ReverseResponse {
  lat: number;
  lon: number;
  address: Address;
  label: string;
  short: string;
  street?: { id: number; name: string; distance: number; lon: number; lat: number };
  place?: SearchResult;
  admins?: { level: number; name: string; osm_id: number }[];
}

interface CategoryGroupInfo { id: string; icon: string; color: string; label: Record<string, string> }
interface CategoryInfo {
  id: string;
  group: string;
  icon: string;
  label: Record<string, string>;
  synonyms?: string[];
  rank: number;
}

type RouteMode = 'car' | 'foot' | 'bike' | 'taxi' | 'truck' | 'motorcycle';

interface RouteRequest {
  points: [number, number][];   // [lon, lat]
  mode?: RouteMode;
  language?: Language;
  alternatives?: number;
  avoid_tolls?: boolean;
  avoid_highways?: boolean;
  shortest?: boolean;
  heading?: number;
}

interface RouteStep {
  type: string;
  modifier: string;
  instruction: string;
  verbal?: string;
  street_names?: string[];
  distance: number;        // metres
  duration: number;        // seconds
  geometry_start: number;  // index into Route.geometry
  geometry_end: number;
  roundabout_exit?: number;
  toll?: boolean;
  highway?: boolean;
  ferry?: boolean;
  sign?: { exit_number?: string[]; branch?: string[]; toward?: string[] };
}

interface RouteLeg { distance: number; duration: number; steps: RouteStep[] }

interface Route {
  id: string;
  mode: RouteMode;
  distance: number;               // metres
  duration: number;               // seconds
  geometry: [number, number][];   // [lon, lat]
  bbox: [number, number, number, number];  // [minLon, minLat, maxLon, maxLat]
  legs: RouteLeg[];
  summary: string;
  has_toll?: boolean;
  has_highway?: boolean;
  has_ferry?: boolean;
  recommended: boolean;
}

interface RouteResponse { routes: Route[]; language: string; engine: string; warnings?: string[] }

interface MatrixRequest {
  points?: [number, number][];    // symmetric shorthand; [lon, lat]
  sources?: [number, number][];
  targets?: [number, number][];
  mode?: RouteMode;
  avoid_tolls?: boolean;
  avoid_highways?: boolean;
  shortest?: boolean;
}

interface MatrixCell {
  source: number;
  target: number;
  distance: number | null;   // metres; null = no path
  duration: number | null;   // seconds; null = no path
}

interface MatrixResponse {
  mode: RouteMode;
  sources: number;
  targets: number;
  cells: MatrixCell[];
  rows: MatrixCell[][];      // rows[source][target]
  engine: string;
}

interface IsochroneRequest {
  point: [number, number];   // [lon, lat]
  mode?: RouteMode;
  minutes?: number[];        // mutually exclusive with metres
  metres?: number[];         // mutually exclusive with minutes
  polygons?: boolean;        // send explicitly; absent means lines through this client
  denoise?: number;          // 0..1
  generalize?: number;       // metres
}

interface IsochroneResponse {
  type: 'FeatureCollection';
  features: FeatureCollection['features'];   // each with contour_minutes or contour_metres
  mode: RouteMode;
  engine: string;
}

type UsageProduct =
  | 'tiles' | 'search' | 'geocoding' | 'places'
  | 'routing' | 'matrix' | 'isochrone' | 'static' | 'other';

interface UsageTotal {
  product: UsageProduct;
  requests: number;   // served, billable
  denied: number;     // refused, never billable
}

interface UsagePoint extends UsageTotal {
  hour: string;       // start of the hour, ISO 8601 UTC
}

interface UsageQuota {
  limit: number;
  used: number;
  remaining: number;  // the type says -1 when unlimited; /api/usage omits `quota` for unlimited keys instead
  resets: string;     // ISO 8601 UTC
}

interface UsageReport {
  key: string;
  name: string;
  from: string;
  to: string;
  requests: number;
  denied: number;
  products: UsageTotal[];
  series?: UsagePoint[];   // only with { series: true }
  quota?: UsageQuota;      // only for keys with a monthly limit
}

interface StatusSources {
  tiles: string[];       // every served PMTiles archive, e.g. ['uzbekistan', 'buildings-ml']
  terrain: boolean;
  places: boolean;       // Overture places overlay
  buildings_ml: boolean; // Microsoft ML building footprints overlay
}

interface Status {
  uptime_s: number;
  tiles: boolean;
  search: boolean;
  routing: boolean;      // live health check
  photos: boolean;
  docs: number;          // indexed places
  built_at: string;
  attribution: string;
  bounds?: [number, number, number, number];   // [minLon, minLat, maxLon, maxLat]
  maxzoom?: number;
  sources?: StatusSources;   // absent on older servers
}