Служба Elevation

  1. Обзор
  2. Запросы данных о высоте
    1. Запросы данных о высоте места
    2. Запросы данных о высоте пути
  3. Ответы на запросы о высоте
    1. Состояние службы Elevation
    2. Результаты службы Elevation
  4. Примеры использования службы Elevation

Обзор

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

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

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

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

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

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

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

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

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

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

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

{
  locations[]: LatLng
}

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

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

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

Литерал объекта 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 – указывает на неизвестную ошибку.

Успешное выполнение обратного вызова следует проверять по коду состояния google.maps.ElevationStatus.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 === google.maps.ElevationStatus.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',
    opacity: 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 !== google.maps.ElevationStatus.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).

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

Текущей странице
Документации
Google Maps Javascript API
Google Maps Javascript API
Продуктах
Нужна помощь? Обратитесь в службу поддержки.