Определение высоты

/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.234.8|158.823.0|120.010.0

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

Для заданного поля 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.234.8|158.823.0|120.010.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://geo.rustore.ru/api/elevation?api_key=<YOUR_API_KEY>"

Ответ

{"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://geo.rustore.ru/api/elevation?api_key=<YOUR_API_KEY>"

Ответ

{"locations":[{"lat":0.000000,"lon":0.000000},{"lat":0.100000,"lon":0.100000}],"height":[null,null]}
Was this information helpful?