Перейти к основному содержимому

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

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

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

Запрос​

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

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

Имя поляФорматОписаниеПример
api_keyhex-stringДоступ к сервисам.api_key=fa749bace6d8a3b1....
jsonstringТело POST-запроса с параметрами, необходимыми для получения интересующих данных о высотах.N/A

JSON запроса

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

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

Поле Формат Описание Пример json с данным полем Пример ответа сервиса
locations

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

• Список координат (см. ниже).

[ {"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 знаков после запятой).

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

Для заданного поля 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 с данным полем Пример ответа сервиса
rangeBoolean

Флаг, при установке которого в 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_distanceInteger

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

Исходный маршрут из последовательных точек разбивается на отрезки длиной 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_precisionInteger

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

Исходный маршрут из последовательных точек разбивается на отрезки длиной 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
      ]
   ]
}

Ответ​

к сведению

Если для какой-то точки не удается определить высоту, вместо значения в метрах возвращается 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://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 ]}