QazMaps API v1

Геокодер, обратный геокодер, маршруты, матрица времени и расстояний, изохроны и карточки организаций по Казахстану. Базовый адрес — /v1 на этом сервере. Машиночитаемое описание — openapi.yaml (подходит для Postman, Insomnia и генераторов клиентов).

Быстрый старт

curl -H "X-Api-Key: $QAZMAPS_KEY" \
  "https://<домен>/v1/geocode?q=%D0%B0%D0%B1%D0%B0%D1%8F%2052&limit=2"

Ответ — JSON. Координаты везде в WGS 84 и в порядке «долгота, широта» (lon,lat), как в GeoJSON. Строки запроса кодируйте в UTF-8 (encodeURIComponent).

Ключ

Каждый запрос, кроме /v1/openapi.yaml, передаёт ключ одним из способов:

Ключ показывается один раз при выдаче — у нас хранится только его хеш, восстановить ключ нельзя, можно выпустить новый. Ответы разрешены для любого источника (CORS *): ключ можно использовать из веб-приложения, но тогда его видят пользователи — заведите для фронтенда отдельный ключ.

Лимиты и учёт

У ключа есть лимит запросов в минуту (по тарифу). Можно сделать короткий всплеск до минутного лимита, дальше запросы восстанавливаются равномерно (лимит / 60 в секунду). Нормализация ограничена ещё и числом адресов в минуту — у тарифа свой лимит.

Ошибки

Тело ошибки: {"error": "описание"}.

Атрибуция

Каждый ответ с данными содержит поле attribution — строку, которую нужно показывать пользователям рядом с результатами (на карте, в списке, в карточке):

Где возможно, делайте «OpenStreetMap» ссылкой на openstreetmap.org/copyright. Все источники и лицензии — на странице /copyright.

Условия

• Данные OpenStreetMap доступны вам по лицензии ODbL 1.0. Полученные через API данные OSM и результаты на их основе можно хранить, обрабатывать и распространять на условиях ODbL: с атрибуцией, а производные базы данных — под той же лицензией. Эти условия не ограничивают ваши права на OSM-часть данных.
• Адреса адресного регистра — открытые данные портала data.egov.kz; их использование и повторная публикация свободны.
• Показывайте пользователям атрибуцию из поля attribution.
• Условия ограничивают только доступ к сервису: ключ выдаётся одному клиенту и не передаётся третьим лицам, действуют лимиты частоты и тариф. При нарушении ключ может быть отключён.

Полный текст условий на казахском и русском языках будет опубликован до запуска платных тарифов.

Поиск: /geocode

Адреса, улицы, населённые пункты и организации с автодополнением — по русским, казахским, альтернативным и старым названиям (переименованная улица находится по прежнему названию, совпавшее показывается в old_name). Опечатки допускаются. Выше — совпадение с начала слова, затем объекты внутри bbox, затем ближайшие к lon,lat (или к центру bbox; по умолчанию — к центру Алматы).

Ответ 200

{
  "attribution": "© OpenStreetMap contributors (ODbL) · Адреса: «Открытые данные» data.egov.kz",
  "results": [
    {
      "id": "37056",
      "type": "address",
      "ref": "a32544",
      "name": "проспект Абая, 52",
      "name_kk": "Абай даңғылы, 52",
      "subtitle": "Бостандыкский район, Алматы",
      "kind": "address",
      "old_name": null,
      "approx": false,
      "post_index": null,
      "lon": 76.913402,
      "lat": 43.239724
    }
  ]
}

Обратный геокодер: /reverse

«Что здесь?» — здание под точкой (или ближайший дом в радиусе ~40 м): адрес, этажность, контур и организации внутри.

Ответ 200

{
  "attribution": "© OpenStreetMap contributors (ODbL) · Адреса: «Открытые данные» data.egov.kz",
  "address": "улица Мукагали Макатаева, 127/1",
  "address_kk": "Мұқағали Мақатаев көшесі, 127/1",
  "post_index": null,
  "area": "Алмалинский район, Алматы",
  "levels": 3,
  "building": { "type": "MultiPolygon", "coordinates": [ … ] },
  "pois": [
    { "ref": "w247006982", "kind": "mall", "kind_label": "Торговый центр", "kind_label_kk": "Сауда орталығы",
      "name": "ТРК Mega Park", "name_kk": "\"Mega Park\" СОК", "religion": null }
  ],
  "lon": 76.92866,
  "lat": 43.26374
}

Если здания или адреса в точке нет, соответствующие поля — null, pois — пустой массив.

Маршрут: /route

Маршрут на автомобиле, пешком или на велосипеде и до двух альтернатив — самый быстрый первым. Подсказки на русском. Пустой routes — маршрут построить нельзя (точки вне дорожного графа).

Ответ 200

{
  "attribution": "© OpenStreetMap contributors (ODbL)",
  "routes": [
    {
      "time": 530.3,
      "length": 3.43,
      "coordinates": [[76.928801, 43.238908], [76.928755, 43.239311], …],
      "maneuvers": [
        { "text": "Двигайтесь на север.", "type": 3, "length": 0.045, "time": 16.3, "at": [76.928801, 43.238908] },
        { "text": "Поверните налево.", "type": 15, "length": 0.089, "time": 34.2, "at": [76.928755, 43.239311] }
      ]
    }
  ]
}

Матрица: /matrix

Время в пути и расстояние по дорогам от каждого источника до каждой цели: распределение заказов по курьерам, ближайший склад, зоны обслуживания. Тело запроса — JSON.

curl -X POST -H "X-Api-Key: $QAZMAPS_KEY" -H "Content-Type: application/json" \
  -d '{"sources": [[76.945329, 43.244304], [76.8697, 43.2028]],
       "targets": [[76.8697, 43.2028], [76.9286, 43.2389], [76.95, 43.26]]}' \
  "https://<домен>/v1/matrix"

Ответ 200

{
  "attribution": "© OpenStreetMap contributors (ODbL)",
  "durations": [[1626, 477, 407], [0, 1226, 1884]],
  "distances": [[10963, 2576, 2241], [0, 7627, 12768]]
}

Точки привязываются к ближайшей дороге в радиусе до 35 км. Если хотя бы у одной точки дороги в этом радиусе нет, матрица не считается: весь запрос получает 400, номер точки в ответе не указан.

Лимиты. Не больше 2 500 элементов (источники × цели, например 50×50) и не больше 100 точек с каждой стороны, иначе 413: разбейте запрос на несколько. Источник и цель — не дальше 400 км друг от друга на автомобиле и 200 км пешком или на велосипеде, иначе 400. Учёт — по посчитанным элементам: запрос 50×50 — до 2 500 единиц, пары без пути (null) не тарифицируются. Лимит частоты расходуется как у остальных методов: один запрос — одна единица. Точки передаются только в теле запроса и не сохраняются.

Изохроны: /isochrone

Куда можно добраться из точки за заданное время: «доставим за 30 минут», пешая доступность магазина. Ответ — GeoJSON FeatureCollection (RFC 7946): по полигону на контур, от большего к меньшему, чтобы меньший рисовался поверх. Его можно сразу передать в источник geojson карты MapLibre.

Ответ 200

{
  "type": "FeatureCollection",
  "attribution": "© OpenStreetMap contributors (ODbL)",
  "features": [
    { "type": "Feature", "properties": { "minutes": 20 },
      "geometry": { "type": "Polygon", "coordinates": [[[76.9406, 43.301635], [76.939846, 43.299653], …]] } },
    { "type": "Feature", "properties": { "minutes": 10 },
      "geometry": { "type": "Polygon", "coordinates": [[[76.9306, 43.267144], [76.929002, 43.264497], …]] } }
  ]
}

properties.minutes — время контура в минутах. Точка привязывается к ближайшей дороге в радиусе до 35 км, и время считается от места привязки; если дороги в этом радиусе нет — 400. Учёт — за запрос, сколько бы контуров в нём ни было.

Организация: /places/{ref}

Карточка организации: название, рубрика, адрес на русском и казахском, район и теги OSM (часы работы, телефон, сайт…). ref — из поля ref ответов /geocode (у организаций) и /reverse.

Ответ 200

{
  "attribution": "© OpenStreetMap contributors (ODbL) · Адреса: «Открытые данные» data.egov.kz",
  "ref": "w247006982",
  "kind": "mall",
  "kind_label": "Торговый центр",
  "kind_label_kk": "Сауда орталығы",
  "name": "ТРК Mega Park",
  "name_kk": "\"Mega Park\" СОК",
  "address": "улица Мукагали Макатаева, 127/1",
  "address_kk": "Мұқағали Мақатаев көшесі, 127/1",
  "area": "Алмалинский район, Алматы",
  "tags": { "phone": "+77021333093", "addr:street": "Мақатаев көшесі", "addr:housenumber": "127/1" },
  "lon": 76.928662,
  "lat": 43.263737
}

tags — теги OpenStreetMap как есть: opening_hours (формат OSM), phone, website, contact:* и др. Неизвестный ref — 404.