高度服務

總覽
海拔要求
1. 位置高度要求
2. 路徑高度要求
海拔回應
1. 高度狀態
2. 高度結果
高度範例

總覽

高度服務可以提供地表位置的高度資料，包含海底位置的深度 (這會傳回負值)。Google 並不是真的對您要求的位置進行精確的海拔測量，這個服務只是使用四個最近的位置內插計算並傳回平均的數值。

ElevationService 物件提供您簡單的介面查詢地球表面位置的高度資料。而且您還可以要求對路徑沿線抽樣高度資料，讓您計算沿著路線的等距高度變化。ElevationService 物件會與接收高度要求的 Google Maps API 高度服務通訊，然後傳回高度資料。

請注意，這些要求有速率的限制，以避免對服務的濫用。如果您想要改為對靜止的已知位置計算高度，請參閱高度 Web 服務文件。

您可以透過高度服務開發步行和單車騎乘的應用程式、行動定位的應用程式，或是低解析度的測量應用程式。

海拔要求

存取高度服務是非同步的，因為 Google Maps API 需要呼叫外部伺服器。所以，您需要傳遞「回呼」方法，以在要求完成時執行。這個回呼方法會處理結果。請注意，高度服務會傳回一個狀態碼 (ElevationStatus) 以及獨立 ElevationResult 物件的陣列。

ElevationService 能處理兩種類型的要求：

對於獨立、分散之位置的要求，將使用 getElevationForLocations() 方法，而 LocationElevationRequest 物件將會對它傳遞具有一個或多個位置的清單。
對於沿著路徑上一系列相連點的高度要求，將使用 getElevationAlongPath() 方法，這會在 PathElevationRequest 物件內依序傳遞路徑的頂點。沿著路徑要求高度時，您必須同時傳遞參數，指示該路徑沿途要抽取多少樣本數。

這些方法都必須傳遞「回呼」方法來處理傳回的 ElevationResult 和 ElevationStatus 物件。

位置高度要求

LocationElevationRequest 物件常值包含下列欄位：

{
  locations[]: LatLng
}

locations (必要) 定義要傳回海拔資料的地球表面位置。此參數可接受 LatLng 陣列。</p <<

您可以在陣列內傳遞任意數目的座標，只要不超過服務配額即可。請注意，傳遞多個座標時，傳回資料之精確度的解析度，可能會比要求單一座標的資料的情況還要低。

抽樣ˋ路徑高度要求

PathElevationRequest 物件常值包含下列欄位：

{
  path[]: LatLng,
  samples: Number
}

這些欄位說明如下：

path (必要) 定義要傳回海拔資料的地球表面路徑。path 參數使用有兩個或更多 LatLng 物件的陣列，定義一組有兩個或更多的排序 {latitude,longitude} 組合。
samples (必要) 指定要傳回海拔資料的路徑沿途樣本點數。samples 參數將指定的 path 沿著路徑依照順序分成等距的點數。

和位置要求一樣，path 參數指定一組緯度與經度值。然而，和位置要求不同的是，path 指定的是一組有順序的頂點。路徑要求並不是傳回頂點的高度資料，而是「沿著路徑全程」抽取樣本，每個樣本 (包括端點) 之間的距離都是相同的。

海拔回應

Elevation 服務會針對每個有效的要求，向定義的回呼傳回一組 ElevationResult 物件及 ElevationStatus 物件。

高度狀態

個別的高度要求都會在其回呼函式內傳回 ElevationStatus 碼。這個 status 碼會包含下列其中一個值：

OK 指出服務要求成功
INVALID_REQUEST 指出服務要求的格式錯誤
OVER_QUERY_LIMIT 指出要求者已超過配額
REQUEST_DENIED 指出服務沒有完成要求，原因可能是因為參數無效
UNKNOWN_ERROR 指出不明錯誤

您應該檢查此 google.maps.ElevationStatus.OK 的狀態碼，來確認您的回呼已成功。

高度結果

如果成功，回呼函式的 results 引數會包含一組 ElevationResult 物件。這些物件包含下列元素：

location 元素 (包含 LatLng 物件)，代表正在計算高度資料的地點。請注意，針對路徑要求，location 元素會包含路徑沿途的抽樣點。
elevation 元素，指出該位置的海拔，以公尺為單位。
resolution 值，指出以內插計算高度的兩個資料點之間的最大距離 (以公尺為單位)。如果解析度為未知，則不會有此屬性。請注意，如果傳入多個點，海拔資料會變得比較粗糙 (較大的 resolution 值)。如果要讓某個點獲得最正確的海拔值，便應該獨立查詢它。

高度範例

下列程式碼使用 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 顯示該路徑沿途的高度資料。(您必須使用 Google Common Loader 載入此 API)。高度要求是使用 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)。

總覽