海拔高度服務

總覽

海拔高度服務會為地表上的地點提供海拔高度資料,包括海底 (深度傳回負值) 的深度位置。如果 Google 無法在您要求的確切位置提供精確的高度測量結果,則服務會使用四個最近位置的內插值並傳回平均值。

ElevationService 物件提供簡易的介面,方便您查詢地球上的海拔高度資料。此外,您也可以沿路徑要求取樣的高度資料,以便計算路徑上的等距高度變更。ElevationService 物件會與 Google Maps API 海拔高度服務進行通訊,以接收高度要求並傳回高度資料。

透過「高度」服務,您可以開發健行和單車應用程式、行動定位應用程式,或低解析度的調查應用程式。

開始

在 Maps JavaScript API 中使用 Elevation 服務之前,請先確認您已在針對 Maps JavaScript API 相同的專案中,在 Google Cloud Console 中啟用 Elevation API。

查看已啟用的 API 清單:

  1. 前往 Google Cloud Console
  2. 按一下「選取專案」按鈕,然後選取您為 Maps JavaScript API 設定的專案,然後按一下「開啟」
  3. 資訊主頁的 API 清單中,尋找 Elevation API
  4. 如果清單中有這個 API,表示您已完成所有設定。如果 API 未列出 API,請啟用該 API:
    1. 選取頁面頂端的「ENABLE API」,即可顯示「Library」(資料庫) 分頁標籤。或者,從左側選單中選取 [程式庫]
    2. 搜尋「Elevation API」,然後從結果清單中選取 API。
    3. 選取「啟用」。程序完成後,Elevation API 會顯示在資訊主頁的 API 清單中。

價格與政策

定價

新的即付即用定價方案已於 2018 年 7 月 16 日生效,適用於地圖介面集、路徑介面集和地點介面集。若要進一步瞭解使用 JavaScript Elevation 服務的全新定價和用量限制,請參閱 Elevation API 的使用方法和計費方式

頻率限制

請留意其他要求的頻率限制:

無論有多少使用者共用同一個專案,系統都會對每位使用者工作階段套用頻率限制。首次載入 API 時,系統會分配初始的初始配額。這個配額用盡後,API 則會每秒對額外的要求執行頻率限制。如果在特定時間範圍內發出太多要求,API 會傳回 OVER_QUERY_LIMIT 回應代碼。

個別工作階段頻率限制可避免在用戶端要求中使用用戶端服務。如要為靜態和已知的位置計算高度,請使用 Elevation API 網路服務

政策

使用 Elevation 服務時,必須遵循 Elevation API 所述的政策

海拔高度要求

由於 Google Maps API 必須呼叫外部伺服器,因此存取 Elevation 服務的過程並非同步。因此,您必須傳遞回呼方法,以便在要求完成時執行。這個回呼方法應處理結果。請注意,海拔高度服務會傳回狀態碼 (ElevationStatus) 和單獨的 ElevationResult 物件陣列。

ElevationService 會處理兩種要求:

  • 使用 getElevationForLocations() 方法針對獨立且離散位置的要求,使用 LocationElevationRequest 物件傳送一或多個位置的清單。
  • 使用 getElevationAlongPath() 方法在路徑上沿著一系列連接點發出的高度高度要求,此方法會在 PathElevationRequest 物件中傳送一系列經過排序的路徑端點。要求路徑沿途的高度時,您必須傳遞參數,指出您要沿著該路徑取樣的樣本數。

這些方法都必須傳遞回呼方法,用於處理傳回的 ElevationResultElevationStatus 物件。

位置海拔高度要求

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

{
  locations[]: LatLng
}

locations (必填) 定義要傳回高度資料的地球地點。這個參數接受 LatLng 的陣列。

只要不超過服務配額,您可以在陣列中傳遞任意數量的多個座標。請注意,傳遞多個座標時,任何傳回資料的準確率可能會低於請求單一座標的資料。

取樣路徑海拔高度要求

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

{
  path[]: LatLng,
  samples: Number
}

這些欄位的說明如下:

  • path (必填) 定義地球上用於傳回高度資料的路徑。path 參數會使用兩個以上的 LatLng 物件陣列,定義兩組或更多排序的 {緯度,經度} 組合。
  • 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 物件,將地圖點擊轉譯為高度要求:

TypeScript

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

  infowindow.open(map);

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

function displayLocationElevation(
  location: google.maps.LatLng,
  elevator: google.maps.ElevationService,
  infowindow: google.maps.InfoWindow
) {
  // Initiate the location request
  elevator
    .getElevationForLocations({
      locations: [location],
    })
    .then(({ results }) => {
      infowindow.setPosition(location);

      // 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");
      }
    })
    .catch((e) =>
      infowindow.setContent("Elevation service failed due to: " + e)
    );
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;

JavaScript

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

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

function displayLocationElevation(location, elevator, infowindow) {
  // Initiate the location request
  elevator
    .getElevationForLocations({
      locations: [location],
    })
    .then(({ results }) => {
      infowindow.setPosition(location);
      // 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");
      }
    })
    .catch((e) =>
      infowindow.setContent("Elevation service failed due to: " + e)
    );
}

window.initMap = initMap;
查看範例

查看範例

下列範例使用一組座標建構折線,並使用 Google 視覺化 API 顯示該路徑中的高度資料。(您必須使用 Google Common Loader 載入這個 API)。使用 PathElevationRequest 建構高度要求:

TypeScript

// 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 },
    { lat: 36.606, lng: -118.0638 },
    { lat: 36.433, lng: -117.951 },
    { lat: 36.588, lng: -116.943 },
    { lat: 36.34, lng: -117.468 },
    { 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;
查看範例

查看範例