Описание

/v1/elevation - точка вызова сервиса, который предоставляет возможность получения данных о высоте над уровнем моря. Сервис позволяет запрашивать высоту для:

отдельной точки на карте;
набора не связанных между собой точек;
маршрута - последовательности связанных между собой точек (для этого используется поле resample_distance в json'е запроса).

Запрос

Запросы к API возможны с помощью HTTP POST.

Обязательные параметры POST-запроса

Имя поля

Формат

Описание

Пример

api_key

hex-string

Доступ к сервисам

api_key=fa749bace6d8a3b1....

json

string

Тело POST-запроса с параметрами, необходимыми для получения интересующих данных о высотах.

JSON запроса

JSON передается в теле запроса.

Обязательные поля

Поле

Формат

Описание

Пример json'а с данным полем

Пример ответа сервиса

locations

В данное поле можно передавать координаты в одном из 3х допустимых форматов:

Список координат:

[ {"lat": 56.1, "lon": 43.2}, {"lat": 56.2, "lon": 43.3}]

Закодированная строка: точки маршрута, специальным образом закодированные в строку (смотрите также: Декодирование ломаной маршрута). Например, полилинию в таком формате возвращает сервис построения маршрутов (поле ответа "shape").

"s{cplAfiz{pCa]xBxBx`AhC|gApBrz@{[h..."

Строка: одна и более координат, разделенных символом |. Используются координаты в формате lat,lon, где:
- lat - широта (используется до 6 знаков после запятой);
- lon - долгота (используется до 6 знаков после запятой).

152.2, 34.8|158.8, 23.0|120.0, 10.0

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

Для заданного поля locations сервис возвращает набор высот в метрах. Количество высот равно количеству точек в locations.

{
   "locations":[
      {
         "lat":55.601897,
         "lon":37.581305
      },
      {
         "lat":55.885040,
         "lon":37.680869
      }
   ]
}

{
   "locations":[
      {
         "lat":55.601897,
         "lon":37.581305
      },
      {
         "lat":55.885040,
         "lon":37.680869
      }
   ],
   "height":[
      201,
      139
   ]
}

Необязательные поля

Поле

Формат

Описание

Пример json'а с данным полем

Пример ответа сервиса

range

Boolean

Флаг, при установке которого в true вместо одномерного массива "height" сервис возвращает двумерный массив "range_height", в котором содержатся пары значений. Первое - расстояние в метрах от предыдущей точки locations; второе - высота.

Флаг удобен для построения профиля высот, а также для расчета уклона для подъемов и спусков.

Значение по умолчанию: false.

{
   "range":true,
   "locations":[
      {
         "lat":55.601897,
         "lon":37.581305
      },
      {
         "lat":55.885040,
         "lon":37.680869
      }
   ]
}

{
   "locations":[
      {
         "lat":55.601897,
         "lon":37.581305
      },
      {
         "lat":55.885040,
         "lon":37.680869
      }
   ],
   "range_height":[
      [
         0,
         201
      ],
      [
         32131,
         139
      ]
   ]
}

resample_distance

Integer

Значение в метрах для указания расстояния между точками, для которых необходимо получить высоты.

Исходный маршрут из последовательных точек разбивается на отрезки длиной resample_distance. Сервис возвращает сформированные таким образом точки и значения высот для этих точек.

Пример использования: есть маршрут пользователя, необходимо построить для него профиль высот с высотами на расстоянии 50 метров друг от друга.

Значение по умолчанию: поле отсутствует, то есть сервис возвращает по одному значению высоты на одну указанную координату.

{
   "resample_distance":10000,
   "locations":[
      {
         "lat":55.601897,
         "lon":37.581305
      },
      {
         "lat":55.885040,
         "lon":37.680869
      }
   ]
}

{
   "locations":[
      {
         "lat":55.601897,
         "lon":37.581305
      },
      {
         "lat":55.690027,
         "lon":37.612137
      },
      {
         "lat":55.778150,
         "lon":37.643109
      },
      {
         "lat":55.866264,
         "lon":37.674221
      },
      {
         "lat":55.885040,
         "lon":37.680869
      }
   ],
   "range_height":[
      [
         0,
         201
      ],
      [
         10000,
         143
      ],
      [
         20000,
         161
      ],
      [
         30000,
         151
      ],
      [
         32131,
         139
      ]
   ]
}

height_precision

Integer

Количество знаков после запятой в значении высоты.

Дробные значения для высоты нужны, например, для большей точности и плавности в профиле высот.

Возможные значения: 0-2.

Значение по умолчанию: 0 (высота - целое число).

{
   "height_precision":2,
   "locations":[
      {
         "lat":55.601897,
         "lon":37.581305
      },
      {
         "lat":55.885040,
         "lon":37.680869
      }
   ]
}

{
   "locations":[
      {
         "lat":55.601897,
         "lon":37.581305
      },
      {
         "lat":55.885040,
         "lon":37.680869
      }
   ],
   "height":[
      200.94,
      138.84
   ]
}

Ответ

Если для какой-то точки не удается определить высоту, вместо значения в метрах возвращается null.

Имя поля

Формат

Описание

Пример

locations

Формат поля ответа совпадает с форматом, выбранным для запроса.

В данном поле возвращаются координаты, для которых была запрошена высота.

Формат "список координат":

"locations":[
      {
         "lat":55.601897,
         "lon":37.581305
      },
      {
         "lat":55.885040,
         "lon":37.680869
      }
   ]

Формат "закодированная строка":

"s{cplAfiz{pCa]xBxBx`AhC|gApBrz@{[h..."

Формат "строка":

152.2, 34.8|158.8, 23.0|120.0, 10.0

height

Массив высот.

В ответе присутствует это поле, если в запросе не задано "range":true.

Если в запросе не указано поле "resample_distance", количество значений в массиве "height" совпадает с количеством точек, переданных в запросе.

Если же поле "resample_distance" указано, то количество высот соответствует количеству точек на полилинии locations, между которыми расстояние, равное "resample_distance".

"height":[221,172,206,188,153]

range_height

Массив пар значений x и y:

x - суммарное расстояние в метрах от начала маршрута. Для первой координаты это всегда 0м.

y - высота в метрах для координаты по заданному индексу.

В ответе присутствует это поле, если в запросе задано "range":true.

Количество пар в массиве "range_height" определяется по тем же правилам, что и в массиве "height".

"range_height":[[0,221],[248,172],[902,206],[11308,188],[1601,153]]

Примеры

Запрос с единственной координатой

curl -X POST \
  -H "Content-type: application/json" \
  -H "Accept: application/json" \
  -d '{"locations":"55.601897, 37.581305"}' \
  "https://demo.maps.mail.ru/v1/elevation?api_key=test"

Ответ

{"locations":"55.601897, 37.581305","height":[201]}

Запрос с координатами, для которых нет данных о высотах

curl -X POST \
  -H "Content-type: application/json" \
  -H "Accept: application/json" \
  -d '{"locations":[{"lat":0.0,"lon":0.0}, {"lat":0.1,"lon":0.1}]}' \
  "https://demo.maps.mail.ru/v1/elevation?api_key=test"

Ответ

{"locations":[{"lat":0.000000,"lon":0.000000},{"lat":0.100000,"lon":0.100000}],"height":[null,null]}