Quickstart

A map on a page, a place search against it, and a route drawn between two points. No build step for the first part; npm for the rest if you want it.

1. Get a key#

Restrict the key to your own origins while you are still in the console — http://localhost:5173 for development, plus wherever you will deploy. A key with no origin restriction works from anywhere, which is only appropriate for a key that stays on a server.

2. Put a map on the page#

html

<!doctype html>
<html>
<body>
  <div id="map" style="width:100%;height:420px"></div>

  <script src="https://uzmaps.ndc.uz/v1/uzmaps.js?apikey=YOUR_KEY"></script>
  <script>
    uzmaps.ready(function () {
      window.map = new uzmaps.Map({
        container: 'map',
        center: [69.2401, 41.2995],   // Tashkent, [lon, lat]
        zoom: 12,
      });
    });
  </script>
</body>
</html>

That is the whole integration. The key and the server are read from the script tag, and the stylesheet is injected by the script — there is no <link> to add.

Open it. If the map is blank, check the browser console: a 403 means the key's origin list does not include where you are serving from.

3. Search for a place#

The script tag also gives you an HTTP client, already carrying the same key:

const api = new uzmaps.Client();

const { results } = await api.search('Chorsu');
console.log(results[0].name, results[0].lat, results[0].lon);

map.selectPlace(results[0], { fly: true });

selectPlace moves the camera and highlights the result. If you only want the camera, map.flyTo({ center: [lon, lat], zoom: 16 }).

4. Draw a route#

const trip = await api.route({
  points: [
    [69.2401, 41.2995],
    [69.2870, 41.3131],
  ],
  mode: 'car',
});

map.showRoutes(trip.routes);

const first = trip.routes[0];
console.log(first.distance, 'm', first.duration, 's');

Distances are metres and durations are seconds. mode accepts car, foot, bike, taxi, truck, motorcycle and bus.

5. Move to npm when you have a bundler#

The script tag and the npm package are the same engine. Switching gains you TypeScript types, tree shaking and control over the MapLibre version:

bash

npm install @uzmaps/engine @uzmaps/api maplibre-gl

import { UzMap } from '@uzmaps/engine';
import { UzMapClient } from '@uzmaps/api';
import 'maplibre-gl/dist/maplibre-gl.css';

const map = new UzMap({
  container: 'map',
  serverUrl: 'https://uzmaps.ndc.uz',
  apiKey: import.meta.env.VITE_UZMAPS_KEY,
  center: [69.2401, 41.2995],
  zoom: 12,
});

const api = new UzMapClient({
  baseUrl: 'https://uzmaps.ndc.uz',
  apiKey: import.meta.env.VITE_UZMAPS_KEY,
});

The one difference: with npm you pass serverUrl and apiKey explicitly, because there is no script tag to read them from.

Where next#

API keys and quotas — origin restrictions, rate limits, what counts against your allowance
@uzmaps/engine — every option, method and event on the map
HTTP API — calling the API without the map at all