Обзор
Сервис Elevation предоставляет данные о высоте местности на поверхности Земли, включая глубину на дне океана (для которой возвращаются отрицательные значения). В тех случаях, когда Google не располагает точными данными о высоте в запрашиваемом вами месте, сервис интерполирует данные и возвращает усредненное значение, используя четыре ближайших местоположения.
Объект ElevationService предоставляет простой интерфейс для запроса данных о высоте местоположения на Земле. Кроме того, вы можете запрашивать выборочные данные о высоте вдоль маршрутов, что позволяет рассчитать равноудаленные изменения высоты вдоль маршрутов. Объект ElevationService взаимодействует с API Google Maps Elevation Service, который принимает запросы на данные о высоте и возвращает их.
С помощью сервиса Elevation вы можете разрабатывать приложения для пеших и велосипедных прогулок, мобильные приложения для определения местоположения или приложения для низкоразрешающей геодезической съемки.
Начиная
Прежде чем использовать сервис Elevation в JavaScript API для работы с картами, убедитесь, что API Elevation включен в консоли Google Cloud в том же проекте, который вы настроили для JavaScript API для работы с картами.
Чтобы просмотреть список включенных API:
- Перейдите в консоль Google Cloud .
- Нажмите кнопку «Выбрать проект» , затем выберите тот же проект, который вы настроили для API JavaScript карт, и нажмите «Открыть» .
- В списке API на панели управления найдите Elevation API .
- Если вы видите API в списке, значит, все в порядке. Если API отсутствует в списке, включите его:
- В верхней части страницы выберите «Включить API» , чтобы отобразить вкладку «Библиотека» . В качестве альтернативы, в меню слева выберите «Библиотека» .
- Найдите Elevation API , затем выберите его из списка результатов.
- Выберите «Включить» . После завершения процесса Elevation API появится в списке API на панели управления .
Цены и политика
Цены
Чтобы узнать о ценообразовании и политике использования сервиса JavaScript Elevation, см. раздел «Использование и выставление счетов для API Elevation».
Политики
Использование сервиса Elevation должно осуществляться в соответствии с правилами, описанными для API Elevation .
Запросы на изменение высоты
Доступ к сервису Elevation осуществляется асинхронно, поскольку API Google Maps должен обращаться к внешнему серверу. По этой причине необходимо передать метод обратного вызова , который будет выполнен после завершения запроса. Этот метод обратного вызова должен обрабатывать результат(ы). Обратите внимание, что сервис Elevation возвращает код состояния ( ElevationStatus ) и массив отдельных объектов ElevationResult .
ElevationService обрабатывает два типа запросов:
- Запросы на получение отдельных, дискретных местоположений выполняются с помощью метода
getElevationForLocations(), которому передается список из одного или нескольких местоположений в виде объектаLocationElevationRequest. - Запросы на определение высоты для ряда соединенных точек вдоль пути выполняются с помощью метода
getElevationAlongPath(), которому передается упорядоченный набор вершин пути в объектеPathElevationRequest. При запросе высоты вдоль пути необходимо также передать параметр, указывающий, сколько выборок вы хотите взять вдоль этого пути.
Каждый из этих методов также должен передавать метод обратного вызова для обработки возвращаемых объектов ElevationResult и ElevationStatus .
Запросы на определение высоты местоположения
Литерал объекта LocationElevationRequest содержит следующее поле:
{ locations[]: LatLng }
locations (обязательный) определяет местоположение на Земле, из которого следует получать данные о высоте. Этот параметр принимает массив значений LatLng .
В массиве можно передавать любое количество координат, при условии, что не превышены квоты сервиса. Обратите внимание, что при передаче нескольких координат точность возвращаемых данных может быть ниже, чем при запросе данных для одной координаты.
Запросы на определение высоты траектории, полученные методом выборки
Литерал объекта PathElevationRequest содержит следующие поля:
{ path[]: LatLng, samples: Number }
Ниже приведено описание этих полей:
-
path(обязательный) определяет путь на Земле, для которого необходимо получить данные о высоте. Параметрpathопределяет набор из двух или более упорядоченных пар {широта, долгота}, используя массив из двух или более объектовLatLng. -
samples(обязательный) указывает количество точек выборки вдоль пути, для которых необходимо вернуть данные о высоте. Параметрsamplesделит заданныйpathна упорядоченный набор равноудаленных точек вдоль пути.
Как и в случае с запросами местоположения, параметр path задает набор значений широты и долготы. Однако, в отличие от запроса местоположения, path задает упорядоченный набор вершин. Вместо возврата данных о высоте в вершинах, запросы path отбираются вдоль всей длины пути , причем каждая выборка находится на равном расстоянии друг от друга (включая конечные точки).
Реакции на изменение высоты
Для каждого корректного запроса служба Elevation вернет в определенную функцию обратного вызова набор объектов ElevationResult вместе с объектом ElevationStatus .
Статус высоты
Каждый запрос на изменение высоты возвращает код ElevationStatus в своей функции обратного вызова. Этот код status будет содержать одно из следующих значений:
-
OKчто означает успешное выполнение запроса на обслуживание. -
INVALID_REQUESTуказывает на то, что запрос на обслуживание был неправильно сформирован. -
OVER_QUERY_LIMITуказывает на то, что запрашивающая сторона превысила квоту. -
REQUEST_DENIEDуказывает на то, что запрос не был выполнен службой, вероятно, из-за недопустимого параметра. -
UNKNOWN_ERRORуказывает на неизвестную ошибку
Вам следует убедиться в успешности выполнения функции обратного вызова, проверив код состояния OK .
Результаты измерения высоты
В случае успеха аргумент results вашей функции обратного вызова будет содержать набор объектов ElevationResult . Эти объекты содержат следующие элементы:
- Элемент
location(содержащий объектыLatLng), отображающий позицию, для которой вычисляются данные о высоте. Обратите внимание, что для запросов маршрута набор элементовlocationбудет содержать точки выборки вдоль маршрута. - Элемент
elevation, указывающий высоту местоположения в метрах. - Значение
resolution, указывающее максимальное расстояние между точками данных, из которых была интерполирована высота, в метрах. Это свойство будет отсутствовать, если разрешение неизвестно. Обратите внимание, что данные о высоте становятся более грубыми (более высокие значенияresolution) при обработке нескольких точек. Для получения наиболее точного значения высоты для точки следует запрашивать ее независимо.
Примеры высотных отметок
Следующий код преобразует щелчок по карте в запрос высоты с использованием объекта LocationElevationRequest :
Машинопись
async function init(): Promise<void> { const [{ InfoWindow }, { ElevationService }] = await Promise.all([ google.maps.importLibrary('maps'), google.maps.importLibrary('elevation'), ]); const mapElement = document.querySelector('gmp-map')!; const innerMap = mapElement.innerMap; const elevator = new ElevationService(); const infowindow = new InfoWindow(); infowindow.open(innerMap); // Add a listener for the click event. Display the elevation for the LatLng of // the click inside the infowindow. innerMap.addListener('click', (event: google.maps.MapMouseEvent) => { displayLocationElevation(event.latLng!, elevator, infowindow, innerMap); }); } function displayLocationElevation( location: google.maps.LatLng, elevator: google.maps.ElevationService, infowindow: google.maps.InfoWindow, map: google.maps.Map ) { // Format numeric values to two decimal places const formatter = new Intl.NumberFormat(undefined, { maximumFractionDigits: 2, }); // Initiate the location request elevator .getElevationForLocations({ locations: [location], }) .then(({ results }) => { if (results[0]) { const { elevation, location: resultLocation } = results[0]; infowindow.setPosition(resultLocation); infowindow.setContent( `The elevation at ${String(resultLocation)} <br>is ${formatter.format(elevation)} meters.` ); } else { infowindow.setPosition(location); infowindow.setContent('No results found'); } infowindow.open(map); }) .catch((e: unknown) => { infowindow.setContent( `Elevation service failed due to: ${String(e)}` ); }); } void init();
JavaScript
async function init() { const [{ InfoWindow }, { ElevationService }] = await Promise.all([ google.maps.importLibrary('maps'), google.maps.importLibrary('elevation'), ]); const mapElement = document.querySelector('gmp-map'); const innerMap = mapElement.innerMap; const elevator = new ElevationService(); const infowindow = new InfoWindow(); infowindow.open(innerMap); // Add a listener for the click event. Display the elevation for the LatLng of // the click inside the infowindow. innerMap.addListener('click', (event) => { displayLocationElevation(event.latLng, elevator, infowindow, innerMap); }); } function displayLocationElevation(location, elevator, infowindow, map) { // Format numeric values to two decimal places const formatter = new Intl.NumberFormat(undefined, { maximumFractionDigits: 2, }); // Initiate the location request elevator .getElevationForLocations({ locations: [location], }) .then(({ results }) => { if (results[0]) { const { elevation, location: resultLocation } = results[0]; infowindow.setPosition(resultLocation); infowindow.setContent( `The elevation at ${String(resultLocation)} <br>is ${formatter.format(elevation)} meters.` ); } else { infowindow.setPosition(location); infowindow.setContent('No results found'); } infowindow.open(map); }) .catch((e) => { infowindow.setContent( `Elevation service failed due to: ${String(e)}` ); }); } void init();
В следующем примере строится полилиния по заданному набору координат и отображаются данные о высоте вдоль этого пути с использованием API визуализации Google . (Необходимо загрузить этот API с помощью Google Common Loader.) Запрос на определение высоты формируется с помощью объекта PathElevationRequest :
Машинопись
// Load the Visualization API and the columnchart package. // @ts-ignore TODO update to newest visualization library google.load("visualization", "1", { packages: ["columnchart"] }); function initMap(): void { // The following path marks a path from Mt. Whitney, the highest point in the // continental United States to Badwater, Death Valley, the lowest point. const path = [ { lat: 36.579, lng: -118.292 }, // Mt. Whitney { lat: 36.606, lng: -118.0638 }, // Lone Pine { lat: 36.433, lng: -117.951 }, // Owens Lake { lat: 36.588, lng: -116.943 }, // Beatty Junction { lat: 36.34, lng: -117.468 }, // Panama Mint Springs { lat: 36.24, lng: -116.832 }, ]; // Badwater, Death Valley const map = new google.maps.Map( document.getElementById("map") as HTMLElement, { zoom: 8, center: path[1], mapTypeId: "terrain", } ); // Create an ElevationService. const elevator = new google.maps.ElevationService(); // Draw the path, using the Visualization API and the Elevation service. displayPathElevation(path, elevator, map); } function displayPathElevation( path: google.maps.LatLngLiteral[], elevator: google.maps.ElevationService, map: google.maps.Map ) { // Display a polyline of the elevation path. new google.maps.Polyline({ path: path, strokeColor: "#0000CC", strokeOpacity: 0.4, map: map, }); // Create a PathElevationRequest object using this array. // Ask for 256 samples along that path. // Initiate the path request. elevator .getElevationAlongPath({ path: path, samples: 256, }) .then(plotElevation) .catch((e) => { const chartDiv = document.getElementById( "elevation_chart" ) as HTMLElement; // Show the error code inside the chartDiv. chartDiv.innerHTML = "Cannot show elevation: request failed because " + e; }); } // Takes an array of ElevationResult objects, draws the path on the map // and plots the elevation profile on a Visualization API ColumnChart. function plotElevation({ results }: google.maps.PathElevationResponse) { const chartDiv = document.getElementById("elevation_chart") as HTMLElement; // Create a new chart in the elevation_chart DIV. const chart = new google.visualization.ColumnChart(chartDiv); // Extract the data from which to populate the chart. // Because the samples are equidistant, the 'Sample' // column here does double duty as distance along the // X axis. const data = new google.visualization.DataTable(); data.addColumn("string", "Sample"); data.addColumn("number", "Elevation"); for (let i = 0; i < results.length; i++) { data.addRow(["", results[i].elevation]); } // Draw the chart using the data within its DIV. chart.draw(data, { height: 150, legend: "none", // @ts-ignore TODO update to newest visualization library titleY: "Elevation (m)", }); } declare global { interface Window { initMap: () => void; } } window.initMap = initMap;
JavaScript
// Load the Visualization API and the columnchart package. // @ts-ignore TODO update to newest visualization library google.load("visualization", "1", { packages: ["columnchart"] }); function initMap() { // The following path marks a path from Mt. Whitney, the highest point in the // continental United States to Badwater, Death Valley, the lowest point. const path = [ { lat: 36.579, lng: -118.292 }, // Mt. Whitney { lat: 36.606, lng: -118.0638 }, // Lone Pine { lat: 36.433, lng: -117.951 }, // Owens Lake { lat: 36.588, lng: -116.943 }, // Beatty Junction { lat: 36.34, lng: -117.468 }, // Panama Mint Springs { lat: 36.24, lng: -116.832 }, ]; // Badwater, Death Valley const map = new google.maps.Map(document.getElementById("map"), { zoom: 8, center: path[1], mapTypeId: "terrain", }); // Create an ElevationService. const elevator = new google.maps.ElevationService(); // Draw the path, using the Visualization API and the Elevation service. displayPathElevation(path, elevator, map); } function displayPathElevation(path, elevator, map) { // Display a polyline of the elevation path. new google.maps.Polyline({ path: path, strokeColor: "#0000CC", strokeOpacity: 0.4, map: map, }); // Create a PathElevationRequest object using this array. // Ask for 256 samples along that path. // Initiate the path request. elevator .getElevationAlongPath({ path: path, samples: 256, }) .then(plotElevation) .catch((e) => { const chartDiv = document.getElementById("elevation_chart"); // Show the error code inside the chartDiv. chartDiv.innerHTML = "Cannot show elevation: request failed because " + e; }); } // Takes an array of ElevationResult objects, draws the path on the map // and plots the elevation profile on a Visualization API ColumnChart. function plotElevation({ results }) { const chartDiv = document.getElementById("elevation_chart"); // Create a new chart in the elevation_chart DIV. const chart = new google.visualization.ColumnChart(chartDiv); // Extract the data from which to populate the chart. // Because the samples are equidistant, the 'Sample' // column here does double duty as distance along the // X axis. const data = new google.visualization.DataTable(); data.addColumn("string", "Sample"); data.addColumn("number", "Elevation"); for (let i = 0; i < results.length; i++) { data.addRow(["", results[i].elevation]); } // Draw the chart using the data within its DIV. chart.draw(data, { height: 150, legend: "none", // @ts-ignore TODO update to newest visualization library titleY: "Elevation (m)", }); } window.initMap = initMap;