Служба Elevation

Обзор

Служба Elevation предоставляет сведения о высоте для точек на поверхности Земли, включая впадины на дне океана (значения при этом будут отрицательными). В случаях, когда Google не располагает точными значениями высоты запрашиваемой точки, служба интерполирует данные и возвращает среднее значение по четырем ближайшим местоположениям.

Объект ElevationService предоставляет простой интерфейс для запросов местоположения с целью получения сведений о высоте. Кроме того, вы можете запросить данные о высоте контрольных точек вдоль маршрута для расчета эквидистантного изменения высоты. Объект ElevationService взаимодействует со службой Google Maps API Elevation Service, которая получает запросы данных о высоте и возвращает данные о высоте.

С помощью службы Elevation вы можете создавать приложения для пешеходного и велосипедного туризма, приложения для мобильного позиционирования, а также приложения для топографической съемки с низким разрешением.

Начало работы

Перед использованием службы Elevation в Google Maps JavaScript API убедитесь, что включен Google Maps Elevation API в консоли Google API Console в том же проекте, который вы установили для Google Maps JavaScript API.

Чтобы просмотреть список включенных API:

Перейдите в Google API Console.
Нажмите кнопку Select a project, затем выберите тот же проект, который вы установили для Google Maps JavaScript API, и нажмите Open.
В списке API на странице Dashboard найдите Google Maps Elevation API.
Если этот API присутствует в списке – все установлено. Если этого API в списке нет, включите его:
1. Вверху страницы выберите ENABLE API, чтобы открыть вкладку Library. В качестве альтернативы можно выбрать пункт Library в меню слева.
2. Найдите Google Maps Elevation API и выберите его из списка результатов.
3. Нажмите ENABLE. Когда процесс завершится, Google Maps Elevation API появится в списке API на панели Dashboard.

Правила и ограничения на использование

Квоты

Для службы Elevation действуют следующие ограничения на использование:

Использование службы Elevation в рамках стандартного плана

2 500 бесплатных запросов в день, рассчитывается как сумма обращений на стороне клиента и на стороне сервера; разрешите тарификацию ( разрешить тарификацию), чтобы получить больший размер квоты по цене 0,50 долларов США за 1 000 дополнительных обращений. Максимальный размер квоты составляет 100 000 запросов в день.
512 местоположений в запросе.
50 запросов в секунду, рассчитывается как сумма запросов на стороне клиента и на стороне сервера.

Использование службы Elevation в рамках премиум-плана

Общая ежедневная бесплатная квота 100 000 запросов каждые 24 часа; дополнительные запросы оплачиваются ежегодно приобретаемыми кредитами Maps API.
512 местоположений в запросе.
Без ограничений запросов по одному проекту на стороне клиента в секунду. Обратите внимание, что API на стороне сервера ограничен 50 запросами в секунду.

Лимит частоты применяется к сеансу каждого пользователя независимо от количества пользователей проекта.

Ограничение по частоте предотвращает использование служб на стороне клиента для массовых запросов. Если вам требуется расчет высоты для постоянных известных мест, используйте веб-службу Google Maps Elevation API.

Политики

Служба Elevation должна использоваться в соответствии с правилами, описанными для Google Maps Elevation API.

Запросы данных о высоте

Доступ к службе Elevation осуществляется асинхронно, поскольку Google Maps API требуется отправить вызов на внешний сервер. Поэтому вам необходимо передать метод обратного вызова, который будет выполнен после завершения запроса. Этот метод обратного вызова должен обработать результаты. Служба Elevation возвращает код состояния (ElevationStatus) и массив отдельных объектов ElevationResult.

ElevationService может обрабатывать два типа запросов:

Запросы отдельных дискретных мест, использующие метод getElevationForLocations(), которому передается список из одного или нескольких мест в объекте LocationElevationRequest.
Запросы высоты ряда связанных точек вдоль пути, использующие метод getElevationAlongPath(), которому передается упорядоченный набор вершин путей в объекте PathElevationRequest. При запросе данных о высоте вдоль путей нужно также передать параметр, указывающий количество контрольных точек вдоль пути, которые вы хотите обработать.

Каждый из этих методов также должен передать метод обратного вызова для обработки возвращенных объектов ElevationResult и ElevationStatus.

Запросы данных о высоте места

Литерал объекта LocationElevationRequest содержит следующее поле:

{
  locations[]: LatLng
}

locations (обязательный параметр) – определяет место (или места) на земной поверхности для получения данных о высоте. Этот параметр принимает массив значений LatLng.

Вы можете передать любое количество координат в массиве, если при этом не превышается квота службы. Обратите внимание, что при передаче координат нескольких точек точность полученных данных может быть ниже, чем при запросе данных для одной точки.

Образцы запросов данных о высоте пути

Литерал объекта PathElevationRequest содержит следующие поля:

{
  path[]: LatLng,
  samples: Number
}

Назначение этих полей объясняется ниже.

path (обязательный параметр) – определяет путь на земной поверхности для предоставления данных о высоте. Параметр path определяет набор из двух или более упорядоченных пар {latitude,longitude}, используя массив из двух или более объектов LatLng.
samples (обязательный параметр) – указывает количество контрольных точек вдоль пути, для которого требуется получить данные о высоте. Параметр samples разделяет указанный параметром path путь на ряд равноудаленных точек вдоль всего пути.

Как в запросах местоположения, параметр path указывает набор значений широты и долготы. Однако, в отличие от запросов местоположения, параметр path указывает упорядоченный набор вершин ломаной линии. Вместо возврата значений высоты только для вершин запросы пути собирают данные о высоте вдоль всего пути через равные интервалы (включая конечные точки).

Ответы на запросы о высоте

Для каждого корректного запроса служба Elevation возвращает заданному обратному вызову набор объектов ElevationResult вместе с объектом ElevationStatus.

Состояния службы Elevation

Каждый запрос высоты возвращает код ElevationStatus в функции обратного вызова. Код status будет содержать одно из следующих значений:

OK – указывает, что запрос службы был успешным.
INVALID_REQUEST – указывает, что запрос службы был неправильно сформирован.
OVER_QUERY_LIMIT – указывает, что запрашивающее приложение превысило квоту.
REQUEST_DENIED – указывает, что служба не выполнила запрос, вероятно из-за недопустимого параметра.
UNKNOWN_ERROR – указывает на неизвестную ошибку.

Успешное выполнение обратного вызова следует проверять по коду состояния OK.

Результаты службы Elevation

В случае успеха аргумент results функции обратного вызова будет содержать набор объектов ElevationResult. Эти объекты содержат следующие элементы:

Элемент location (содержащий объекты LatLng) позиции, для которой рассчитываются данные о высоте. Для запросов пути набор элементов location будет содержать контрольные точки вдоль всего пути.
Элемент elevation, указывающий высоту местоположения в метрах.
Значение resolution, указывающее максимальное расстояние в метрах между точками, по которым были интерполированы значения высоты. Данное свойство будет отсутствовать, если разрешение неизвестно. Обратите внимание на то, что при передаче нескольких точек точность данных о высоте будет снижена (более высокие значения resolution). Для получения наиболее точных значений высоты для точки необходимо отправлять раздельные запросы.

Примеры использования службы Elevation

Следующий код преобразует нажатие на карте в запрос высоты, используя объект LocationElevationRequest:

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 8,
    center: {lat: 63.333, lng: -150.5},  // Denali.
    mapTypeId: 'terrain'
  });
  var elevator = new google.maps.ElevationService;
  var infowindow = new google.maps.InfoWindow({map: map});

  // Add a listener for the click event. Display the elevation for the LatLng of
  // the click inside the infowindow.
  map.addListener('click', function(event) {
    displayLocationElevation(event.latLng, elevator, infowindow);
  });
}

function displayLocationElevation(location, elevator, infowindow) {
  // Initiate the location request
  elevator.getElevationForLocations({
    'locations': [location]
  }, function(results, status) {
    infowindow.setPosition(location);
    if (status === 'OK') {
      // Retrieve the first result
      if (results[0]) {
        // Open the infowindow indicating the elevation at the clicked position.
        infowindow.setContent('The elevation at this point <br>is ' +
            results[0].elevation + ' meters.');
      } else {
        infowindow.setContent('No results found');
      }
    } else {
      infowindow.setContent('Elevation service failed due to: ' + status);
    }
  });
}

<div id="map"></div>

/* Always set the map height explicitly to define the size of the div
 * element that contains the map. */
#map {
  height: 100%;
}
/* Optional: Makes the sample page fill the window. */
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}

 <!-- Replace the value of the key parameter with your own API key. -->
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 8,
    center: {lat: 63.333, lng: -150.5},  // Denali.
    mapTypeId: 'terrain'
  });
  var elevator = new google.maps.ElevationService;
  var infowindow = new google.maps.InfoWindow({map: map});

  // Add a listener for the click event. Display the elevation for the LatLng of
  // the click inside the infowindow.
  map.addListener('click', function(event) {
    displayLocationElevation(event.latLng, elevator, infowindow);
  });
}

function displayLocationElevation(location, elevator, infowindow) {
  // Initiate the location request
  elevator.getElevationForLocations({
    'locations': [location]
  }, function(results, status) {
    infowindow.setPosition(location);
    if (status === 'OK') {
      // Retrieve the first result
      if (results[0]) {
        // Open the infowindow indicating the elevation at the clicked position.
        infowindow.setContent('The elevation at this point <br>is ' +
            results[0].elevation + ' meters.');
      } else {
        infowindow.setContent('No results found');
      }
    } else {
      infowindow.setContent('Elevation service failed due to: ' + status);
    }
  });
}

Просмотр примера (elevation-simple.html).

В следующем примере по указанному набору координат строится ломаная линия и с помощью Google Visualization API отображаются данные о высоте вдоль этого пути. (Этот API необходимо загрузить с помощью загрузчика Google Common Loader.) Запрос высоты создается с помощью PathElevationRequest:

// Load the Visualization API and the columnchart package.
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.
  var 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

  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 8,
    center: path[1],
    mapTypeId: 'terrain'
  });

  // Create an ElevationService.
  var 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
  }, plotElevation);
}

// Takes an array of ElevationResult objects, draws the path on the map
// and plots the elevation profile on a Visualization API ColumnChart.
function plotElevation(elevations, status) {
  var chartDiv = document.getElementById('elevation_chart');
  if (status !== 'OK') {
    // Show the error code inside the chartDiv.
    chartDiv.innerHTML = 'Cannot show elevation: request failed because ' +
        status;
    return;
  }
  // Create a new chart in the elevation_chart DIV.
  var 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.
  var data = new google.visualization.DataTable();
  data.addColumn('string', 'Sample');
  data.addColumn('number', 'Elevation');
  for (var i = 0; i < elevations.length; i++) {
    data.addRow(['', elevations[i].elevation]);
  }

  // Draw the chart using the data within its DIV.
  chart.draw(data, {
    height: 150,
    legend: 'none',
    titleY: 'Elevation (m)'
  });
}

<div>
  <div id="map" style="height:250px;"></div>
  <div id="elevation_chart"></div>
</div>

/* Always set the map height explicitly to define the size of the div
 * element that contains the map. */
#map {
  height: 100%;
}
/* Optional: Makes the sample page fill the window. */
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}

<script src="https://www.google.com/jsapi"></script>
 <!-- Replace the value of the key parameter with your own API key. -->
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>

// Load the Visualization API and the columnchart package.
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.
  var 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

  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 8,
    center: path[1],
    mapTypeId: 'terrain'
  });

  // Create an ElevationService.
  var 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
  }, plotElevation);
}

// Takes an array of ElevationResult objects, draws the path on the map
// and plots the elevation profile on a Visualization API ColumnChart.
function plotElevation(elevations, status) {
  var chartDiv = document.getElementById('elevation_chart');
  if (status !== 'OK') {
    // Show the error code inside the chartDiv.
    chartDiv.innerHTML = 'Cannot show elevation: request failed because ' +
        status;
    return;
  }
  // Create a new chart in the elevation_chart DIV.
  var 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.
  var data = new google.visualization.DataTable();
  data.addColumn('string', 'Sample');
  data.addColumn('number', 'Elevation');
  for (var i = 0; i < elevations.length; i++) {
    data.addRow(['', elevations[i].elevation]);
  }

  // Draw the chart using the data within its DIV.
  chart.draw(data, {
    height: 150,
    legend: 'none',
    titleY: 'Elevation (m)'
  });
}

Просмотр примера (elevation-paths.html).

Все готово!

Обзор

Начало работы

Правила и ограничения на использование

Квоты

Использование службы Elevation в рамках стандартного плана

Использование службы Elevation в рамках премиум-плана

Политики

Запросы данных о высоте

Запросы данных о высоте места

Образцы запросов данных о высоте пути

Ответы на запросы о высоте

Состояния службы Elevation

Результаты службы Elevation

Примеры использования службы Elevation

Оставить отзыв о...

Все готово!

Активация Google Maps JavaScript API

Служба Elevation

Обзор

Начало работы

Правила и ограничения на использование

Квоты

Использование службы Elevation в рамках стандартного плана

Использование службы Elevation в рамках премиум-плана

Политики

Запросы данных о высоте

Запросы данных о высоте места

Образцы запросов данных о высоте пути

Ответы на запросы о высоте

Состояния службы Elevation

Результаты службы Elevation

Примеры использования службы Elevation

Оставить отзыв о...