Документация API и Playground
Введение
OSRMRoute Directions API — это RESTful веб-сервис, созданный для интеграции быстрой высокопроизводительной геопространственной маршрутизации, матриц поездок, поиска адресов (геокодинга) и оптимизации маршрутов в ваши приложения. В этой документации подробно описаны все возможности API, параметры и шаги интеграции.
Аутентификация
Запросы к OSRMRoute API используют уникальный API-ключ для аутентификации. Вы можете добавить свой API-ключ к каждому запросу как query-параметр (?key=YOUR_KEY) или через HTTP-заголовок Authorization (как Bearer-токен).
Any 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).
/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). Идеальный инструмент для оптимизации логистических маршрутов.
/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-сигналах.
/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) и возвращает информацию о названии дороги.
/api/v1/osrm/nearest/v1/{profile}/{coordinates}Параметры (Query Params)
| Параметр | Тип | Статус | По умолчанию | Описание |
|---|---|---|---|---|
| profile | string | Обязательный | driving | Транспортный профиль. |
| coordinates | string | Обязательный | - | Точка для поиска ближайшего. Формат: lon,lat (одна пара). |
| number | integer | Необязательный | 3 | Количество ближайших дорог-кандидатов для поиска. |
Trip API
Решает задачу коммивояжёра (TSP): находит наиболее оптимальный круговой (или открытый) маршрут для посещения заданного набора точек и упорядочивает точки.
/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 или последняя точка). |
Geocoding API
Преобразует адреса в географические координаты (или наоборот). Идеально для интегрированных поисковых систем.
/api/1/geocodeПараметры (Query Params)
| Параметр | Тип | Статус | По умолчанию | Описание |
|---|---|---|---|---|
| q | string | Обязательный | - | Искомый адрес (например: «улица Низами, Баку»). |
| reverse | boolean | Необязательный | false | Должно быть true для обратного геокодинга (поиск от координат к адресу). |
Isochrone API
Возвращает полигоны географических зон, достижимых из заданной точки за заданное время или расстояние.
/api/1/isochroneПараметры (Query Params)
| Параметр | Тип | Статус | По умолчанию | Описание |
|---|---|---|---|---|
| point | string | Обязательный | - | Центральная точка. Формат: lat,lon. |
| time_limit | integer | Необязательный | 600 | Лимит времени в пути (в секундах). |
Route Optimization API
Оптимизирует маршруты автопарка (Vehicle Routing Problem). Вычисляет план доставки и перевозок для автомобилей с наименьшими затратами.
/api/1/vrpПараметры (Query Params)
| Параметр | Тип | Статус | По умолчанию | Описание |
|---|---|---|---|---|
| vehicles | array | Обязательный | [] | Список транспортных средств (id, вместимость, начальный адрес и т. д.). |
| services | array | Обязательный | [] | Адреса для обслуживания (id, координаты, время обслуживания и т. д.). |
Location Clustering API
Группирует заданные координаты по их географической близости и плотности (разбивает на кластеры).
/api/1/clusterПараметры (Query Params)
| Параметр | Тип | Статус | По умолчанию | Описание |
|---|---|---|---|---|
| customers | array | Обязательный | [] | Координаты клиентов и веса для кластеризации. |