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

Тестовый ключ:YOUR_API...

Введение

OSRMRoute Directions API — это RESTful веб-сервис, созданный для интеграции быстрой высокопроизводительной геопространственной маршрутизации, матриц поездок, поиска адресов (геокодинга) и оптимизации маршрутов в ваши приложения. В этой документации подробно описаны все возможности API, параметры и шаги интеграции.

Аутентификация

Запросы к OSRMRoute API используют уникальный API-ключ для аутентификации. Вы можете добавить свой API-ключ к каждому запросу как query-параметр (?key=YOUR_KEY) или через HTTP-заголовок Authorization (как Bearer-токен).

GETAny endpoint

Параметры (Query Params)

Параметр	Тип	Статус	По умолчанию	Описание
key	string	Обязательный	-	Уникальный API-ключ, полученный из вашей личной панели. Этот ключ определяет лимиты ваших запросов.

Коды ошибок

OSRMRoute использует стандартные HTTP-коды статусов и подробные JSON-сообщения об ошибках для указания состояния запроса.

Пояснение структуры ответа

Основные коды статусов и их значение: - **200 OK**: Запрос выполнен успешно. - **400 Bad Request**: Параметры некорректны или отсутствуют. - **401 Unauthorized**: API-ключ не предоставлен или недействителен. - **403 Forbidden**: API-ключ заблокирован или неактивен. - **429 Too Many Requests**: Превышен дневной лимит кредитов. - **500 Internal Error**: Произошла внутренняя ошибка системы.

Routing API

Вычисляет самый быстрый и короткий маршрут из точки A в точку B (с промежуточными via-точками). Возвращает пошаговые (turn-by-turn) инструкции и геометрию GeoJSON для разных транспортных профилей (driving, cycling, walking).

GET/api/v1/osrm/route/v1/{profile}/{coordinates}

Параметры (Query Params)

Параметр	Тип	Статус	По умолчанию	Описание
profile	string	Обязательный	driving	Профиль вида транспорта. Поддерживаемые значения: driving (автомобиль), cycling (велосипед), walking (пешеход).
coordinates	string	Обязательный	-	Координаты точек. Формат: lon,lat;lon,lat;lon,lat... (минимум 2 точки).
overview	string	Необязательный	full	Детализация возвращаемой геометрии маршрута: simplified (упрощённая), full (полная геометрия), false (без геометрии).
geometries	string	Необязательный	geojson	Формат геометрии: geojson (объект GeoJSON), polyline (закодированная строка).
steps	boolean	Необязательный	true	Возвращать ли пошаговые инструкции для каждого поворота.

Пояснение структуры ответа

Успешный ответ содержит общее расстояние маршрута (в метрах), время в пути (в секундах), путевые точки и линию маршрута в GeoJSON.

Matrix API

Вычисляет быструю матрицу расстояний и времени в пути между несколькими точками (таблица NxM). Идеальный инструмент для оптимизации логистических маршрутов.

GET/api/v1/osrm/table/v1/{profile}/{coordinates}

Параметры (Query Params)

Параметр	Тип	Статус	По умолчанию	Описание
profile	string	Обязательный	driving	Транспортный профиль (driving, cycling, walking).
coordinates	string	Обязательный	-	Точки матрицы. Формат: lon,lat;lon,lat;lon,lat...
annotations	string	Необязательный	duration,distance	Данные для вычисления: duration (время), distance (расстояние) или оба.

Пояснение структуры ответа

Успешный ответ возвращает двумерную таблицу-матрицу distances (расстояния) и durations (длительности) для каждой комбинации начальной и конечной точек.

Map Matching API

Привязывает неточные GPS-треки к реальной дорожной сети (snap to road). Используется для очистки шума в GPS-сигналах.

GET/api/v1/osrm/match/v1/{profile}/{coordinates}

Параметры (Query Params)

Параметр	Тип	Статус	По умолчанию	Описание
profile	string	Обязательный	driving	Транспортный профиль.
coordinates	string	Обязательный	-	Последовательность GPS-координат для привязки (lon,lat;lon,lat...)
overview	string	Необязательный	full	Точность геометрии сопоставленного маршрута.

Nearest API

Привязывает любую координату к ближайшему реальному сегменту дороги (snap) и возвращает информацию о названии дороги.

GET/api/v1/osrm/nearest/v1/{profile}/{coordinates}

Параметры (Query Params)

Параметр	Тип	Статус	По умолчанию	Описание
profile	string	Обязательный	driving	Транспортный профиль.
coordinates	string	Обязательный	-	Точка для поиска ближайшего. Формат: lon,lat (одна пара).
number	integer	Необязательный	3	Количество ближайших дорог-кандидатов для поиска.

Trip API

Решает задачу коммивояжёра (TSP): находит наиболее оптимальный круговой (или открытый) маршрут для посещения заданного набора точек и упорядочивает точки.

GET/api/v1/osrm/trip/v1/{profile}/{coordinates}

Параметры (Query Params)

Параметр	Тип	Статус	По умолчанию	Описание
profile	string	Обязательный	driving	Транспортный профиль.
coordinates	string	Обязательный	-	Точки для посещения. Формат: lon,lat;lon,lat...
source	string	Необязательный	any	Точка, с которой может начинаться маршрут (any или первая точка).
destination	string	Необязательный	any	Точка, в которой заканчивается маршрут (any или последняя точка).

Directions API

Возвращает пошаговую навигацию между двумя и более точками с чистым списком инструкций (текст, расстояние, время, тип манёвра и координаты). Поддерживает авто, велосипед и пешехода, а также до 3 альтернативных маршрутов в одном вызове.

GET/api/1/directions

Параметры (Query Params)

Параметр	Тип	Статус	По умолчанию	Описание
point	string	Обязательный	lat,lng	Точка: lat,lng. Повторите параметр для каждой остановки (минимум 2).
profile	string	Необязательный	driving	Способ передвижения: driving, cycling или walking.
alternatives	integer	Необязательный	0	Число дополнительно возвращаемых альтернативных маршрутов (0–3).
lang	string	Необязательный	en	Код языка для текста инструкций.

Пояснение структуры ответа

Возвращает { code, profile, routes[], waypoints[] }. У каждого маршрута есть distance (м), duration (с), геометрия GeoJSON и массив instructions[]; каждая инструкция включает text, type, modifier, distance, duration, name и location [lat,lng].

Snap to Road API

Привязывает сырые, неточные GPS-точки к ближайшему положению на дорожной сети. Повторите параметр point для каждой координаты (до 100).

GET/api/1/snap

Параметры (Query Params)

Параметр	Тип	Статус	По умолчанию	Описание
point	string	Обязательный	lat,lng	GPS-точка: lat,lng. Повторите параметр для каждой точки (максимум 100).
profile	string	Необязательный	driving	Дорожная сеть для привязки: driving, cycling или walking.

Пояснение структуры ответа

Возвращает { code, profile, snapped[] }. Каждый элемент содержит исходный input [lat,lng], привязанную позицию [lat,lng], расстояние привязки в метрах и название дороги.

Geocoding API

Преобразует поисковый текст в географические координаты (прямое) или координаты в адрес (обратное). Быстрый автокомплит с устойчивостью к опечаткам — охватывает улицы, адреса и объекты (кафе, магазины, отели, офисы). Идеально для поиска по мере ввода.

GET/api/1/geocode

Параметры (Query Params)

Параметр	Тип	Статус	По умолчанию	Описание
q	string	Обязательный	-	Искомый адрес (например: «улица Низами, Баку»).
reverse	boolean	Необязательный	false	Должно быть true для обратного геокодинга (поиск от координат к адресу).
point	string	Необязательный	lat,lng	Координата (lat,lng) для обратного геокодирования в адрес. Обязательна при reverse=true.
limit	integer	Необязательный	5	Максимальное число результатов (1–20, по умолчанию 5).
lang	string	Необязательный	en	Предпочтительный язык названий результатов (например en, az, ru). По умолчанию en.
lat	number	Необязательный	-	Широта для смещения результатов (ближайшие — выше). Вместе с lon.
lon	number	Необязательный	-	Долгота для смещения результатов. Вместе с lat.
bbox	string	Необязательный	-	Ограничить результаты рамкой: minLon,minLat,maxLon,maxLat.
osm_tag	string	Необязательный	-	Фильтр по тегу OSM, напр. place (населённые пункты) или amenity:cafe. Префикс ! для исключения.
city	string	Необязательный	-	Поднять результаты в этом городе наверх (напр. Bakı), не скрывая остальные.
elastic	boolean	Необязательный	true	Эластичный (нечёткий, высокая полнота) поиск — по умолчанию true. Терпим к опечаткам, отсутствию диакритики (ə↔e), порядку слов, общим словам (metro, rayonu) и номерам домов. false — строгое совпадение.

Примеры

# Смещение к точке, только населённые пункты
GET /api/1/geocode?q=qala&lat=40.41&lon=49.87&osm_tag=place&key=YOUR_KEY

# Поднять город наверх
GET /api/1/geocode?q=market&city=Bakı&key=YOUR_KEY

# Обратное геокодирование (координаты в адрес)
GET /api/1/geocode?reverse=true&point=40.409,49.867&key=YOUR_KEY

Места (POI рядом)

Найдите объекты рядом с точкой — кафе, магазины, отели, банкоматы, аптеки и др. — с фильтром по категории и радиусу, сортировкой по расстоянию.

GET/api/1/places

Параметры (Query Params)

Параметр	Тип	Статус	По умолчанию	Описание
point	string	Обязательный	lat,lng	Центральная координата lat,lng для поиска (обязательно).
radius	number	Необязательный	1	Радиус поиска в километрах (0.05–20, по умолчанию 1).
category	string	Необязательный	-	Фильтр по тегу OSM, напр. amenity:cafe, shop, tourism:hotel. Префикс ! для исключения. Пусто = все POI.
limit	integer	Необязательный	10	Макс. число результатов (1–50, по умолчанию 10).
lang	string	Необязательный	en	Предпочтительный язык названий (напр. en, az, ru).

Autocomplete API

Быстрые, устойчивые к опечаткам подсказки мест по мере ввода, с учётом местоположения.

GET/api/1/autocomplete

Параметры (Query Params)

Параметр	Тип	Статус	По умолчанию	Описание
q	string	Обязательный	-	Текст запроса — допустим частичный ввод.
limit	integer	Необязательный	8	Максимальное число подсказок (1–15).
lang	string	Необязательный	en	Код языка для меток результатов.
lat	number	Необязательный	-	Широта для смещения результатов (необязательно).
lon	number	Необязательный	-	Долгота для смещения результатов (необязательно).
osm_tag	string	Необязательный	-	Фильтр по типу OSM, напр. place:city.

Пояснение структуры ответа

Возвращает { suggestions[], took }. Каждая подсказка содержит label, name, city, state, country, countrycode, type, osm_id и point {lat,lng}.

Batch Geocoding API

Геокодируйте сотни адресов одним запросом — идеально для конвейеров данных и импорта.

POST/api/1/geocode/batch

Параметры (Query Params)

Параметр	Тип	Статус	По умолчанию	Описание
queries	array	Обязательный	[]	Массив строк адресов для геокодирования (макс 100).
lang	string	Необязательный	en	Код языка для меток результатов.
limit	integer	Необязательный	1	Максимум совпадений на запрос (1–5).

Пояснение структуры ответа

Возвращает { results[], count, took }. Каждый результат связывает входной query с массивом hits[]; каждое совпадение содержит label, city, country и point {lat,lng}. Порядок ввода сохраняется.

Timezone API

Часовой пояс IANA, текущее смещение UTC, статус летнего времени и местное время для любой координаты.

GET/api/1/timezone

Параметры (Query Params)

Параметр	Тип	Статус	По умолчанию	Описание
point	string	Обязательный	lat,lng	Координата: lat,lng.
lat	number	Необязательный	-	Широта (вместо point).
lon	number	Необязательный	-	Долгота (вместо point).
timestamp	integer	Необязательный	now	Unix-время (секунды) или дата ISO для расчёта смещения; по умолчанию сейчас.

Пояснение структуры ответа

Возвращает { timezone, point, utc_offset, utc_offset_seconds, dst, abbreviation, local_time, utc_time }. utc_offset — строка +ЧЧ:ММ, dst равно true при летнем времени, а local_time — ISO-метка со смещением пояса.

Elevation API

Высота над уровнем моря в метрах для любой координаты — одна точка или профиль всего маршрута.

GET/api/1/elevation

Параметры (Query Params)

Параметр	Тип	Статус	По умолчанию	Описание
point	string	Обязательный	lat,lng	Координата: lat,lng. Повторяйте для каждой точки (до 100 в GET).

Пояснение структуры ответа

Возвращает { results[], unit:"meters" }, где каждый результат — { point:{lat,lng}, elevation }. elevation — метры над уровнем моря (null, если неизвестно, 0 над морем). Для одной точки также добавляется elevation верхнего уровня. Для больших наборов — POST { points:[[lat,lng],...] } (до 1000).

Boundary Lookup API

Определите, в какой стране, регионе, городе и районе находится координата — при запросе с полигоном границы.

GET/api/1/boundary

Параметры (Query Params)

Параметр	Тип	Статус	По умолчанию	Описание
point	string	Обязательный	lat,lng	Координата: lat,lng.
polygon	boolean	Необязательный	false	true, чтобы также вернуть границу как GeoJSON.
lang	string	Необязательный	en	Код языка для названий.

Пояснение структуры ответа

Возвращает { point, display_name, country, countrycode, state, county, city, district, postcode, osm_id, osm_type }, а при polygon=true — геометрию границы GeoJSON.

Geofencing API

Одним запросом проверьте, в какие ваши зоны попадает каждая точка — полигональные или круговые ограждения.

POST/api/1/geofence

Параметры (Query Params)

Параметр	Тип	Статус	По умолчанию	Описание
fences	array	Обязательный	[]	Массив ограждений: { id?, polygon:[[lat,lng],...] } или { id?, center:[lat,lng], radius_m }. До 100.
points	array	Обязательный	[]	Массив точек [lat,lng] для проверки (до 1000).

Пояснение структуры ответа

Возвращает { results[], count }. Каждый результат — { point:{lat,lng}, inside:[fenceId,...] } со всеми ограждениями, в которые попала точка (пусто, если нет).

Elevation Profile API

Высота в каждой точке пути + общий подъём, спуск и расстояние — полный профиль маршрута.

POST/api/1/elevation/profile

Параметры (Query Params)

Параметр	Тип	Статус	По умолчанию	Описание
points	array	Обязательный	[]	Массив точек [lat,lng] пути (>=2, до 2000).
polyline	string	Необязательный	-	Закодированная полилиния вместо points.

Пояснение структуры ответа

Возвращает { profile[], total_ascent, total_descent, min_elevation, max_elevation, distance, unit }. Каждый элемент — { point, elevation, distance } (метры).

Solar API

Восход, закат, сумерки, солнечный полдень и длина дня для любой координаты и даты.

GET/api/1/solar

Параметры (Query Params)

Параметр	Тип	Статус	По умолчанию	Описание
point	string	Обязательный	lat,lng	Координата: lat,lng.
date	string	Необязательный	today	Дата (YYYY-MM-DD) для расчёта; по умолчанию сегодня.

Пояснение структуры ответа

Возвращает { point, date, sunrise, sunset, solar_noon, dawn, dusk, golden_hour, night_start, night_end, day_length_seconds }. Время в UTC ISO; null в полярный день/ночь.

Geometry Utilities API

Расстояние, азимут, площадь, центроид, упрощение и polyline encode/decode — геометрия как сервис.

POST/api/1/geometry

Параметры (Query Params)

Параметр	Тип	Статус	По умолчанию	Описание
op	string	Обязательный	distance	Операция: distance, bearing, destination, midpoint, length, area, centroid, simplify, polyline_encode или polyline_decode.
from	array	Необязательный	[lat,lng]	Начальная точка [lat,lng].
to	array	Необязательный	[lat,lng]	Конечная точка [lat,lng].
path	array	Необязательный	[]	Массив [lat,lng] (length/simplify/polyline_encode).
polygon	array	Необязательный	[]	Кольцо [lat,lng] (area).

Пояснение структуры ответа

Возвращает { op, ... } с результатом операции, напр. { distance, unit }, { bearing_deg }, { point }, { area, unit }, { path } или { polyline }.

Coordinate Conversion API

Преобразование широты/долготы в UTM и MGRS и обратно.

GET/api/1/convert

Параметры (Query Params)

Параметр	Тип	Статус	По умолчанию	Описание
point	string	Обязательный	lat,lng	Координата lat,lng для конвертации в UTM/MGRS.
mgrs	string	Необязательный	-	Строка MGRS для обратной конвертации в координату.

Пояснение структуры ответа

Возвращает { point, mgrs, utm:{ zone, band, easting, northing, hemisphere } }. При mgrs= — { mgrs, point }.

Country Info API

Валюта, телефонный код, языки, столица и флаг любой страны по ISO-коду или названию.

GET/api/1/country

Параметры (Query Params)

Параметр	Тип	Статус	По умолчанию	Описание
code	string	Обязательный	AZ	Код страны ISO 3166 alpha-2 или alpha-3 (напр. AZ или AZE).
name	string	Необязательный	-	Название страны вместо кода.

Пояснение структуры ответа

Возвращает { name, official_name, cca2, cca3, capital, region, subregion, currency:{code,name,symbol}, calling_code, languages[], flag, latlng, population }.

Isochrone API

Возвращает полигоны географических зон, достижимых из заданной точки за заданное время или расстояние.

GET/api/1/isochrone

Параметры (Query Params)

Параметр	Тип	Статус	По умолчанию	Описание
point	string	Обязательный	-	Центральная точка. Формат: lat,lon.
time_limit	integer	Необязательный	600	Лимит времени в пути (в секундах).

Route Optimization API

Оптимизирует маршруты автопарка (Vehicle Routing Problem). Вычисляет план доставки и перевозок для автомобилей с наименьшими затратами.

POST/api/1/vrp

Параметры (Query Params)

Параметр	Тип	Статус	По умолчанию	Описание
vehicles	array	Обязательный	[]	Список транспортных средств — у каждого id, необязательная вместимость и начальная точка в виде массива [lon, lat] (сначала долгота).
services	array	Обязательный	[]	Точки для обслуживания — у каждой id, координаты в виде массива [lon, lat] (сначала долгота) и необязательное время обслуживания. Порядок координат такой же, как во всех наших эндпоинтах.

Location Clustering API

Группирует заданные координаты по их географической близости и плотности (разбивает на кластеры).

POST/api/1/cluster

Параметры (Query Params)

Параметр	Тип	Статус	По умолчанию	Описание
customers	array	Обязательный	[]	Координаты клиентов и веса для кластеризации.

Сервис

Транспорт

Overview

Geometries

Инструкции Steps

Альтернативные маршруты

Загрузка модуля карты...

Готовые примеры кодаСтатичный пример

# Запрос OSRMRoute cURL
curl -X GET "https://docs.osrmroute.com/api/v1/osrm/route/v1/driving/49.8671,40.4093;49.8700,40.4120?key=YOUR_API_KEY&overview=full&geometries=geojson&steps=true&alternatives=false" \
  -H "Accept: application/json"

Официальные SDK

Ноль зависимостей, полная типизация, все эндпоинты. Первый запрос — меньше чем за минуту.

osrmrouteosrmrouteПосмотреть SDK