Документация
Как подключить карту Kazmap: JS SDK для сайта и HTTP API для всего остального.
Быстрый старт: JS SDK
Войдите в кабинет, добавьте организацию и создайте браузерный ключ. В нём нужно указать адреса сайтов (Origin), с которых он работает, например https://example.kz.
Подключите SDK и стили и создайте карту:
<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. Параметры:
Для сборщиков есть ESM-версия; maplibre-gl в ней — зависимость вашего проекта, а воркер MapLibre кладётся в статику сайта и указывается в workerUrl:
// 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 в адресе (для тайлов и случаев, где заголовок не поставить):
curl 'https://kazmap.kz/v1/geocode/search?q=Абая+10' \
-H 'X-Api-Key: kzg_live_…'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, если пишете в поддержку.
| Статус | Код | Что значит |
|---|---|---|
| 401 | api_key_missing, api_key_invalid, api_key_expired | Ключ не передан, неверный или отозван. |
| 403 | origin_not_allowed | Адрес сайта не входит в список Origin браузерного ключа. |
| 403 | insufficient_scope | У ключа нет права на этот метод. |
| 429 | quota_exceeded | Месячный лимит продукта исчерпан. Заголовок Retry-After — секунды до начала следующего месяца. |
| 429 | rate_limited | Слишком частые запросы. Подождите Retry-After секунд и повторите. |
| 503 | authz_unavailable | Проверка ключа временно недоступна. Повторите через Retry-After секунд. |
Квоты и лимиты запросов
Месячная квота — на организацию, общая для всех её ключей, отдельно по продуктам: Карта, Геокодер, Поиск мест, Маршруты. Расход по дням и месяц против лимита — в кабинете, раздел «Расход». Тестовые ключи (kzg_test_…) — до 1 000 запросов в сутки на продукт, в счета не идут.
Когда лимит исчерпан, поведение зависит от тарифа: либо 429 quota_exceeded до начала месяца, либо запросы проходят и учитываются сверх лимита для доплаты. В кабинете появляется предупреждение на 80 % и 100 % лимита.
Кроме квоты действует ограничение частоты запросов. В ответах есть заголовки RateLimit-Policy и RateLimit (черновик IETF httpapi-ratelimit-headers): сколько запросов осталось в окне и когда оно закончится. При 429 и 503 есть Retry-After. Повторяйте запросы с паузой и случайной добавкой, не чаще, чем разрешено.
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 с числом принятых и отброшенных. Эти запросы не считаются в квоту.
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}]}'