К содержимому

Документация

Как подключить карту Kazmap: JS SDK для сайта и HTTP API для всего остального.

Быстрый старт: JS SDK

Войдите в кабинет, добавьте организацию и создайте браузерный ключ. В нём нужно указать адреса сайтов (Origin), с которых он работает, например https://example.kz.

Подключите SDK и стили и создайте карту:

index.html
<link rel="stylesheet" href="https://platform.kazmap.kz/sdk/v1/kazmap.css">
<script src="https://platform.kazmap.kz/sdk/v1/kazmap.js"></script>

<div id="map" style="height: 420px"></div>
<script>
  const map = kazmap.createMap({
    container: 'map',
    key: 'kzg_live_…',          // браузерный ключ из кабинета
    center: [76.93, 43.26],     // [долгота, широта]
    zoom: 11,
    lang: 'ru',          // язык страницы: ru, kk или en
  });
</script>

createMap возвращает обычную карту MapLibre GL (maplibregl.Map) со стилем Kazmap: на ней работают маркеры, слои и события MapLibre. Параметры:

  • container элемент или его id
  • key браузерный ключ из кабинета
  • center центр, [долгота, широта]; по умолчанию Алматы
  • zoom масштаб; по умолчанию 11
  • lang язык подписей: ru, kk или en
  • apiBase адрес API, по умолчанию https://kazmap.kz; http:// допустим только для localhost, 127.0.0.1 и *.localhost (разработка)
  • geolocate позиция кнопки геолокации, по умолчанию 'top-right'; false — без кнопки
  • mapOptions остальные настройки maplibregl.Map (pitch, minZoom…); style, transformRequest и атрибуцию изменить нельзя
  • workerUrl путь к maplibre-gl-worker.mjs — только для ESM-версии (см. ниже)

Для сборщиков есть ESM-версия; maplibre-gl в ней — зависимость вашего проекта, а воркер MapLibre кладётся в статику сайта и указывается в workerUrl:

app.js
// npm install maplibre-gl@6
// Из https://platform.kazmap.kz/sdk/v1/ в ваш проект:
//   kazmap.esm.js, kazmap.css — рядом с кодом;
//   maplibre-gl-worker.mjs и maplibre-gl-shared.mjs — в статику сайта, рядом друг с другом (public/kazmap/)
import { createMap } from './kazmap.esm.js';
import './kazmap.css';

const map = createMap({
  container: 'map',
  key: 'kzg_live_…',
  workerUrl: '/kazmap/maplibre-gl-worker.mjs',
});

Атрибуция «© Kazmap, © OpenStreetMap» показывается всегда и не отключается: этого требует лицензия данных (ODbL).

Кнопка геолокации включена по умолчанию. Запрос разрешения браузер показывает только после нажатия на неё.

HTTP API

Передайте ключ заголовком X-Api-Key или параметром key в адресе (для тайлов и случаев, где заголовок не поставить):

shell
curl 'https://kazmap.kz/v1/geocode/search?q=Абая+10' \
  -H 'X-Api-Key: kzg_live_…'
url
https://kazmap.kz/v1/styles/…/style.json?key=kzg_live_…

Серверный ключ храните на бэкенде и не отдавайте в браузер. В браузере используйте браузерный ключ с ограничением по Origin.

Что считается и по какому продукту

ПродуктАдреса
Карта maps/v1/tiles/basemap/*, /v1/styles/*, /fonts/*, /sprites/*, /v1/tiles/relief*
Геокодер geocode/v1/geocode/search, /autocomplete, /reverse, /lookup
Поиск мест search/v1/places*, /v1/categories
Маршруты routing/v1/route

Полное описание методов и схем — в спецификации OpenAPI.

Ошибки

Ошибки приходят в формате Problem Details (RFC 9457) с полями code и trace_id. Укажите trace_id, если пишете в поддержку.

СтатусКодЧто значит
401api_key_missing, api_key_invalid, api_key_expiredКлюч не передан, неверный или отозван.
403origin_not_allowedАдрес сайта не входит в список Origin браузерного ключа.
403insufficient_scopeУ ключа нет права на этот метод.
429quota_exceededМесячный лимит продукта исчерпан. Заголовок Retry-After — секунды до начала следующего месяца.
429rate_limitedСлишком частые запросы. Подождите Retry-After секунд и повторите.
503authz_unavailableПроверка ключа временно недоступна. Повторите через Retry-After секунд.

Квоты и лимиты запросов

Месячная квота — на организацию, общая для всех её ключей, отдельно по продуктам: Карта, Геокодер, Поиск мест, Маршруты. Расход по дням и месяц против лимита — в кабинете, раздел «Расход». Тестовые ключи (kzg_test_…) — до 1 000 запросов в сутки на продукт, в счета не идут.

Когда лимит исчерпан, поведение зависит от тарифа: либо 429 quota_exceeded до начала месяца, либо запросы проходят и учитываются сверх лимита для доплаты. В кабинете появляется предупреждение на 80 % и 100 % лимита.

Кроме квоты действует ограничение частоты запросов. В ответах есть заголовки RateLimit-Policy и RateLimit (черновик IETF httpapi-ratelimit-headers): сколько запросов осталось в окне и когда оно закончится. При 429 и 503 есть Retry-After. Повторяйте запросы с паузой и случайной добавкой, не чаще, чем разрешено.

HTTP
RateLimit-Policy: "default";q=10;w=1     # q — запросов в секунду на ключ
RateLimit: "default";r=7;t=1               # r — осталось, t — секунд до полного ведра
Retry-After: 2                             # только при 429 и 503

Данные о местоположении

Подключая карту Kazmap, вы соглашаетесь передавать нам обезличенные данные о местоположении и движении ваших пользователей. Ниже — что именно мы собираем и как с этим обращаемся. Юридические условия — в оферте.

Что собираем

  • Точки: время, широта и долгота, точность, скорость и направление, если их даёт устройство.
  • Случайный идентификатор устройства. Он хранится в браузере и меняется раз в сутки. Сырым мы его не сохраняем.
  • Не собираем и не храним: IP-адрес, User-Agent, имя, почту, телефон и любые другие признаки личности.

Зачем

  • Чтобы исправлять и дополнять карту: дороги, повороты, ограничения.
  • На втором этапе — чтобы считать дорожную ситуацию (пробки) по скорости потока.

Только с согласия пользователя

SDK никогда сам не запрашивает разрешение на геолокацию и не обходит его. Сбор начинается, если пользователь нажал кнопку геолокации на карте и разрешил доступ в браузере или разрешение уже было выдано вашему сайту.

Вы сообщаете своим пользователям об этой передаче в политике конфиденциальности и не отключаете сбор. Принять оферту с этим условием нужно до выпуска первого ключа.

Анонимизация

Идентификатор устройства сразу заменяется на HMAC-SHA256 от пары «организация + устройство» с суточной солью. Соль хранится в секрете и в памяти, не в базе, и каждые сутки меняется: связать одно устройство между днями нельзя.

Отбрасываются неточные точки (хуже 100 м), точки из будущего и старше суток, точки далеко за пределами Казахстана (грубая рамка вокруг страны, приграничные районы соседей в неё попадают) и невозможные скачки скорости (быстрее 250 км/ч).

Срок и место хранения

Сырые точки хранятся 7 дней и удаляются автоматически. Хранение — на серверах в Казахстане. Доступ — только у отдельной роли сервиса и у суперадминистратора.

Для серверных и мобильных интеграций

Точки можно передавать напрямую: POST /v1/telemetry/probes с ключом, у которого есть право telemetry:write. До 500 точек и 256 КБ в запросе; ответ 202 с числом принятых и отброшенных. Эти запросы не считаются в квоту.

shell
curl -X POST 'https://kazmap.kz/v1/telemetry/probes' \
  -H 'X-Api-Key: kzg_live_…' -H 'Content-Type: application/json' \
  -d '{"device_id":"7f1c…","source":"server","points":[
        {"t":"2026-11-18T10:00:00Z","lat":43.25,"lon":76.93,"acc":12,"speed":38}]}'

Оферта

Документация — Kazmap Platform