您已全部設定完成!

若要開始開發,請參閱我們的開發人員文件

啟用 Google Maps JavaScript API

為協助您開始,我們將先引導您使用「Google 開發人員控制台」來執行一些動作:

  1. 建立或選擇專案
  2. 啟用 Google Maps JavaScript API 與相關服務
  3. 建立適當的金鑰
繼續

高度服務

總覽

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

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

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

開始使用

使用 Google Maps JavaScript API 中的海拔服務之前,請先確定已在 Google API Console (您針對 Google Maps JavaScript API 設定的相同專案中) 中啟用 Google Maps Elevation API。

檢視已啟用的 API 清單:

  1. 前往 Google API Console
  2. 按一下 [Select a project] 按鈕,選取您針對 Google Maps JavaScript API 設定的相同專案,然後按一下 [Open]
  3. 對於 [Dashboard] 上的 API 清單,請搜尋 Google Maps Elevation API
  4. 如果您在該清單中看到 API,表示您已設定好。如果列出該 API,請將它啟用:
    1. 在頁面頂端,選取 [ENABLE API] 以顯示 [Library] 標籤。或者,從左側選單,選取 [Library]
    2. 搜尋 Google Maps Elevation API,然後從結果清單中選取它。
    3. 選取 [ENABLE]。當此程序完成時,Google Maps Elevation API 會出現在 [Dashboard] 上的 API 清單中。

使用限制與政策

配額

海拔服務具有下列使用限制:

搭配「標準方案」使用海拔服務

  • 每天可以有 2,500 個免費要求(用戶端與伺服器端查詢合計); 啟用計費功能要存取更高的每日配額,我們便會以每 1000 個額外要求 $0.50 美元向您收費,而每天的要求數目上限則為 100,000 個。
  • 每個要求可以有 512 個位置。
  • 每秒 50 個要求,併入用戶端與伺服器端查詢合併的加總計算。

搭配「進階方案」使用海拔服務

  • 每 24 小時 100,000 個要求的共用每日免費配額;額外要求根據年度購買 Maps APIs Credits 的量執行。
  • 每個要求可以有 512 個位置。
  • 每個專案每秒 無限制 個用戶端要求。請注意,伺服器端 API 限制為每秒 50 個要求。

速率限制適用於每個使用者工作階段,無論有幾個使用者共用相同的專案都是一樣。

每個工作階段的速率限制可防止針對批次要求使用用戶端服務。如果您想要改為對靜止的已知位置計算海拔,請使用 Google Maps Elevation API Web 服務

政策

使用海拔服務時必須符合 Google Maps Elevation API 政策

海拔要求

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

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

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

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

位置高度要求

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

{
  locations[]: LatLng
}

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

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

抽樣ˋ路徑高度要求

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 指出不明錯誤

您應該檢查此 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 === '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 顯示該路徑沿途的高度資料。(您必須使用 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',
    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)

傳送您對下列選項的寶貴意見...

這個網頁
Google Maps JavaScript API
Google Maps JavaScript API
需要協助嗎?請前往我們的支援網頁