Следите за использованием ключа, пока не упёрлись в лимит
Наблюдение за заголовками квоты по ходу работы показывает приближение к лимиту задолго до того, как запрос будет отклонён.
Создаём профиль высот для пешего или велосипедного маршрута
Профиль высот представляет собой просто список точек, у каждой из которых есть высота, отложенный относительно расстояния вдоль маршрута. Эндпоинт высоты возвращает эту высоту для стольких точек, сколько вы отправите, за один вызов.
Отправка маршрута
Передайте последовательность пар широты и долготы в параметре points, разделяя пары вертикальной чертой, а значения внутри пары запятой.
GET /v1/elevation?points=45.8326,6.8652|45.8400,6.8700|45.8475,6.8750{
"status": "ok",
"results": [
{"lat": 45.8326, "lon": 6.8652, "elevation_m": 1035},
{"lat": 45.8400, "lon": 6.8700, "elevation_m": 1210},
{"lat": 45.8475, "lon": 6.8750, "elevation_m": 1390}
]
}Превращаем результаты в профиль
Каждый элемент в results соответствует точке, отправленной на той же позиции. Сопоставьте elevation_m с накопленным расстоянием между соседними точками, которое вы сами вычисляете по координатам, и у вас будут значения x и y для графика профиля без дополнительных запросов.
Более короткий пример с пакетным телом запроса
Если вы предпочитаете отправлять структурированный массив вместо параметра points с разделителями, отправьте POST-запросом JSON-массив объектов с координатами на /v1/elevation так же, как другие эндпоинты принимают пакетные тела запросов.
POST /v1/elevation
Content-Type: application/json
[{"lat": 45.8326, "lon": 6.8652}, {"lat": 45.8400, "lon": 6.8700}]В любом случае стоимость одинакова, один запрос за точку, поэтому выбирайте тот формат, который проще собрать из уже имеющейся у вас структуры данных: строку запроса из массива или JSON-массив, собранный тем же способом.
Выбор шага между точками
Маршруту с сотней GPS-точек через каждые несколько метров не нужна высота для каждой из них, чтобы построить читаемый профиль. Если на длинном маршруте брать каждую двадцатую или пятидесятую точку либо пересэмплировать маршрут на равные интервалы расстояния, график останется плавным, а число запросов сократится, ведь каждая точка в параметре points считается одним запросом.
Ошибка, которой стоит избегать
Считать elevation_m точным до сантиметра значит требовать от данных больше, чем нужно для профиля высот. Значение достаточно точно, чтобы построить плавный читаемый профиль и вычислить разумный суммарный набор высоты, но две точки в метре друг от друга на ровной местности могут дать немного разные значения, которые ничего не говорят о реальном рельефе. Стройте график и расчёт набора высоты так, чтобы они допускали такой небольшой шум, а не считали каждое колебание реальной особенностью маршрута.
Пограничный случай: вода или неотображённая местность
Точка, попадающая на открытую воду или в область с малым количеством данных о высоте, может вернуть низкое или постоянное значение вместо ошибки. Если ваш маршрут включает паромную переправу или участок по отдалённой местности, сверяйте необычно ровные участки профиля с самой картой, а не считайте, что число всегда описывает твёрдую землю.
Сколько это стоит
Профиль из ста точек означает сто запросов, что с запасом укладывается в 2 500 бесплатных запросов в день, которые входят в каждый ключ или доступны с одного адреса без ключа. Инструменту планирования маршрутов, который ежедневно обслуживает много пользователей, всё же стоит следить за заголовками квоты, поскольку профили высот популярных маршрутов накапливаются быстрее, чем одиночные запросы.
Данные о высоте превращают плоскую карту в то, по чему пешеход или велосипедист действительно может планировать маршрут. Полный список параметров приведён на странице документации по определению высоты.