/api/iso — точка вызова сервиса расчёта области достижимости.
Сервис позволяет рассчитать контуры областей (изолинии), которые можно достичь из выбранного местоположения при указанном ограничении — на время в пути либо на пройденное расстояние. Рассчитанные контуры возвращаются в виде замкнутой линии либо полигона, которые можно отобразить на карте.
Возможные варианты построения изолиний:
Запрос передаётся в формате JSON в HTTP body. JSON запроса состоит из обязательных и необязательных полей. В URL запроса должны быть заданы обязательные параметры.
Простой пример JSON запроса:
{
"locations": [
{"lat": 55.796932, "lon": 37.537849}
],
"costing": "pedestrian",
"speed": 5.6,
"contours": [
{"time": 15},
{"time": 30}
],
"id": "Iso_Test",
"generalize": 5
}
По данному запросу вокруг заданной координаты будут сгенерированы две изохроны, ограничивающие области, которые пешеход может пройти от координаты соответственно за 15 и 30 минут. Скорость пешехода принимается за 5.6 км/ч.
| Имя параметра | Формат | Описание | Пример |
|---|---|---|---|
api_key |
hex-string | Ключ доступа к сервисам | fa749bace6d8a3b1.... |
| Имя поля | Формат | Описание | Пример |
|---|---|---|---|
locations |
list | Точка, относительно которой осуществляется расчёт области достижимости. lat и lon — широта и долгота точки в градусах (6 знаков после запятой). |
[{"lat": 55.796932, "lon": 37.537849}] |
contours |
list | Список параметров для построения изолиний. Каждый параметр определяет метрику (время либо расстояние) и цвет контура. Возможные поля: time — время в минутах (от 1 до 120); distance — расстояние в километрах (может быть дробным). На каждый контур можно задать только одну метрику. Максимальное число контуров в одном запросе: 3. |
[{"time": 15}, {"time": 30}] |
| Имя поля | Формат | Описание | Пример |
|---|---|---|---|
speed |
float | Скорость в км/ч. Применима только для пешеходных (pedestrian) и велосипедных (bicycle) изохрон. Если не указана, используется скорость по умолчанию: 5 км/ч для пешеходов и 20 км/ч для велосипедистов. |
"speed": 20.1 |
costing |
string | Тип транспорта для построения маршрута: auto (по умолчанию) — автомобильный; truck (не поддерживается) — грузовой; pedestrian — пешеходный; bicycle — велосипедный. |
"costing": "pedestrian" |
id |
string | Идентификатор запроса, который возвращается вместе с ответом — позволяет точно установить соответствие запроса и ответа | "id": "Iso_Test" |
costing_options |
dict | Параметры расчёта маршрута. Для различных типов транспорта используются различные опции и ограничения, аналогичные тем, которые используются в сервисе Построение маршрута. | {"use_border_crossing": 0, "use_tolls": 0} |
units |
string | Единица измерения расстояния в ответе: kilometers (по умолчанию) — километры; miles — мили. |
"units": "miles" |
generalize |
float | Допустимое отклонение в метрах при генерализации кривой контура по алгоритму Рамера–Дугласа–Пекера. Уменьшение числа точек кривой может приводить к пересечению смежных контуров и к самопересечениям. | "generalize": 5 |
polygons |
boolean | Определяет структуру GeoJSON в ответе: false (по умолчанию) — возвращать линии контуров достижимости; true — возвращать полигоны. |
"polygons": true |
show_locations |
boolean | Возвращать вместе с изолиниями исходные точки (заданные в locations) и точки, заматченные на дорожный граф. false (по умолчанию) — не возвращать; true — возвращать. |
"show_locations": true |
Возвращаемый ответ соответствует структуре GeoJSON.
| Имя поля | Формат | Описание | Пример |
|---|---|---|---|
id |
string | Идентификатор запроса | "id": "Iso_Test" |
type |
string | Тип GeoJSON объекта | "FeatureCollection" |
features |
list | Список объектов GeoJSON. Каждый объект содержит properties и geometry. |
|
properties |
dict | Описание времени и типа достижимости для линии или полигона контура. contour — значение времени в минутах из запроса; metric — тип метрики (time или distance). |
{"contour": 15, "metric": "time"} |
geometry |
dict | Описание контура и его структуры: coordinates — набор координат в формате [lon, lat]; type — тип геометрии (LineString для линий, Polygon для полигонов). |
При отсутствии результата сервис вернёт:
{"status_code": 400, "status": "Bad Request"}
curl -X POST \
-H "Content-type: application/json" \
-H "Accept: application/json" \
-d '{
"locations": [{"lat": 55.796932, "lon": 37.537849}],
"costing": "pedestrian",
"contours": [
{"time": 15, "color": "ff0000"},
{"time": 30, "color": "00ff00"}
],
"id": "Iso_Test",
"generalize": 5
}' \
"/api/iso"
{
"id": "Iso_Test",
"type": "FeatureCollection",
"features": [
{
"properties": {
"contour": 30,
"metric": "time"
},
"geometry": {
"coordinates": [
[37.550148, 55.814228],
[37.549480, 55.814301],
[37.549141, 55.814220],
[37.548851, 55.814262],
"..."
],
"type": "LineString"
}
},
{
"properties": {
"contour": 15,
"metric": "time"
},
"geometry": {
"coordinates": [
[37.537922, 55.798004],
[37.536846, 55.797928],
[37.536957, 55.796932],
[37.537849, 55.796383],
[37.539318, 55.796932],
[37.537922, 55.798004]
],
"type": "LineString"
}
}
]
}
Массив
coordinatesсодержит координаты в формате[longitude, latitude]. Порядок контуров в ответе — от наибольшего к наименьшему значению времени/расстояния.