高度要求和回應

海拔高度要求

Elevation API 要求是以網址字串的形式建構。API 會傳回地球上不同地點的海拔高度資料。指定位置資料的方式有兩種：

  • 做為一或多個 locations 的集合。
  • 以 path 沿途的一系列連續點來指定。

這兩種方式都不是使用經緯度座標來識別位置或路徑端點。本文件會說明 Elevation API 網址的格式，以及可用的參數。

Elevation API 會針對單一點查詢傳回最準確的資料。涉及多個位置的批次查詢可能會傳回準確率較低的資料，尤其是兩個位置彼此相隔時，因為必須取得較順暢的資料。

Elevation API 要求應採用下列格式：

https://maps.googleapis.com/maps/api/elevation/outputFormat?parameters

其中 outputFormat 可以是下列任一值：

  • json (建議使用) 表示輸出格式是 JavaScript Object Notation (JSON)；或
  • xml：表示輸出格式採用 XML 格式，並納入 <ElevationResponse> 節點中。

注意：網址必須正確編碼才有效，且所有網路服務的長度上限為 16384 個字元。建構網址時請注意這項限制。請注意，不同瀏覽器、Proxy 和伺服器可能會有不同的網址字元限制。

使用 API 金鑰的要求必須透過 HTTPS 傳送。

要求參數

向 Elevation API 發出的要求會使用不同的參數，視要求為獨立位置或已排序路徑而定。如果是不連續的位置，海拔高度要求會針對已傳入要求中的特定位置傳回資料；如果是路徑，海拔高度要求會沿著指定路徑「取樣」。

如同所有網址，這裡的參數都會以 &amp; 字元分隔。參數清單及其可能的值表示如下。

所有要求

  • key — (必要) 應用程式的 API 金鑰。為管理配額，此金鑰會識別您的應用程式。瞭解如何取得金鑰。

位置要求

  • locations (必要) 定義要傳回海拔高度資料的地表位置。這個參數接受單一地點做為逗號分隔的 {latitude,longitude} (例如「40.714728,-73.998672」)，或是以陣列或編碼折線形式傳遞的多個經緯度組合。此特定參數有 512 點的限制。詳情請參閱下方的指定位置。

取樣路徑要求

  • path (必要)：定義要傳回海拔高度資料的地表路徑。這個參數會定義兩對或多對已排序 {latitude,longitude} 的組合，定義地表上的路徑。這個參數必須搭配下方所述的 samples 參數使用。這項特定參數有 512 點的限制。詳情請參閱下方的指定路徑。
  • samples (必要) 指定要傳回海拔高度資料的路徑沿途取樣點數量。samples 參數會將指定的 path 分割為路徑沿途中一組已排序的等距點。

指定位置

位置要求是透過使用 locations 參數來指定，表示以經緯度值傳遞的特定位置海拔高度要求。

locations 參數可採用下列引數：

  • 單一座標：locations=40.714728,-73.998672
  • 以直立線 (「|」) 字元分隔的座標陣列：locations=40.714728,-73.998672|-34.397,150.644
  • 一組使用編碼折線演算法編碼的座標：locations=enc:gfo}EtohhU

經緯度座標字串是在以半形逗號分隔的文字字串中使用數字來定義。例如，「40.714728,-73.998672」是有效的 locations 值。緯度和經度值必須能對應到地球表面的有效位置。緯度必須是介於 -90 和 90 之間的任何值，經度值則可以是 -180 到 180 之間的任何值。如果指定的經緯度值無效，您的要求將遭到拒絕。

在陣列或編碼折線中，您最多可以傳送 512 個座標，但仍要建構有效的網址。請注意，傳遞多個座標時，任何傳回資料的解析度準確性，可能會比只要求單一座標資料時更低。在「locations」或「path」參數中超過 512 個點或座標，會傳回 INVALID_REQUEST 回應。

指定路徑

範例路徑要求是透過使用 path 和 samples 參數來表示的，表示對海拔高度資料的要求，是以特定間隔的路徑表示要求。與使用 locations 參數的位置要求一樣，path 參數會指定一組經緯度值。然而與位置要求不同的是，path 會指定一組已排序的端點。路徑要求不會只傳回端點的海拔高度資料，而是會「沿著路徑長度」取樣，由指定的 samples 數量 (包含端點) 決定。

path 參數可接受下列其中一個引數：

  • 兩個以上以半形逗號分隔的座標文字字串陣列，並以直立線 (「|」) 字元分隔：path=40.714728,-73.998672|-34.397,150.644
  • 使用編碼折線演算法編碼的座標：path=enc:gfo}EtohhUxD@bAxJmGF

經緯度座標字串是在以半形逗號分隔的文字字串中使用數字來定義。例如，「40.714728,-73.998672|-34.397, 150.644」為有效的 path 值。緯度和經度值必須能對應到地球表面的有效位置。緯度必須是介於 -90 和 90 之間的任何值，經度值則可以是 -180 到 180 之間的任何值。如果指定的經緯度值無效，您的要求將遭到拒絕。

在陣列或編碼折線中，您最多可以傳送 512 個座標，但仍要建構有效的網址。請注意，傳遞多個座標時，任何傳回資料的解析度準確性，可能會比只要求單一座標資料時更低。在「locations」或「path」參數中超過 512 個點或座標，就會傳回 INVALID_REQUEST 回應。

海拔高度回應

對於每個有效的要求，海拔高度服務會以要求網址內指定的格式傳回海拔高度回應。

ElevationResponse

FieldRequiredTypeDescription
required Array<ElevationResult> See ElevationResult for more information.
requiredElevationStatus See ElevationStatus for more information.
optionalstring

When the service returns a status code other than OK, there may be an additional error_message field within the response object. This field contains more detailed information about thereasons behind the given status code. This field is not always returned, and its content is subject to change.

ElevationStatus

Status codes returned by service.

  • OK indicating the API request was successful.
  • DATA_NOT_AVAILABLE indicating that there's no available data for the input locations.
  • INVALID_REQUEST indicating the API request was malformed.
  • OVER_DAILY_LIMIT indicating any of the following:
    • The API key is missing or invalid.
    • Billing has not been enabled on your account.
    • A self-imposed usage cap has been exceeded.
    • The provided method of payment is no longer valid (for example, a credit card has expired).
  • OVER_QUERY_LIMIT indicating the requestor has exceeded quota.
  • REQUEST_DENIED indicating the API did not complete the request.
  • UNKNOWN_ERROR indicating an unknown error.

當狀態碼不是 OK 時，海拔高度回應物件中可能會多出 error_message 欄位。這個欄位可提供更多詳細資訊，讓您瞭解特定狀態碼背後的原因。

回應中包含 results 陣列，當中包含以下元素：

ElevationResult

FieldRequiredTypeDescription
requirednumber

The elevation of the location in meters.

requiredLatLngLiteral

A location element of the position for which elevation data is being computed. Note that for path requests, the set of location elements will contain the sampled points along the path.

See LatLngLiteral for more information.

optionalnumber

The value indicating the maximum distance between data points from which the elevation was interpolated, in meters. This property will be missing if the resolution is not known. Note that elevation data becomes more coarse (larger resolution values) when multiple points are passed. To obtain the most accurate elevation value for a point, it should be queried independently.

location 物件包含下列元素：

LatLngLiteral

An object describing a specific location with Latitude and Longitude in decimal degrees.

FieldRequiredTypeDescription
requirednumber

Latitude in decimal degrees

requirednumber

Longitude in decimal degrees

位置高度範例

以下範例要求以 JSON 格式表示科羅拉多州丹佛的海拔高度：

網址

https://maps.googleapis.com/maps/api/elevation/json
  ?locations=39.7391536%2C-104.9847034
  &key=YOUR_API_KEY

cURL

curl -L -X GET 'https://maps.googleapis.com/maps/api/elevation/json?locations=39.7391536%2C-104.9847034&key=YOUR_API_KEY'

JSON

{
  "results":
    [
      {
        "elevation": 1608.637939453125,
        "location": { "lat": 39.7391536, "lng": -104.9847034 },
        "resolution": 4.771975994110107,
      },
    ],
  "status": "OK",
}

XML

<ElevationResponse>
 <status>OK</status>
 <result>
  <location>
   <lat>39.7391536</lat>
   <lng>-104.9847034</lng>
  </location>
  <elevation>1608.6379395</elevation>
  <resolution>4.7719760</resolution>
 </result>
</ElevationResponse>

以下範例顯示多個回應 (適用於科羅拉多州丹佛、科羅拉多州和加州死亡谷)。

這項要求示範如何使用 JSON output 旗標：

網址

https://maps.googleapis.com/maps/api/elevation/json
  ?locations=39.7391536%2C-104.9847034%7C36.455556%2C-116.866667
  &key=YOUR_API_KEY

cURL

curl -L -X GET 'https://maps.googleapis.com/maps/api/elevation/json?locations=39.7391536%2C-104.9847034%7C36.455556%2C-116.866667&key=YOUR_API_KEY'

此要求示範如何使用 XML output 標記：

https://maps.googleapis.com/maps/api/elevation/xml?locations=39.7391536,-104.9847034|36.455556,-116.866667&key=YOUR_API_KEY

選取下方的分頁標籤，即可查看 JSON 和 XML 回應範例。

JSON

{
  "results":
    [
      {
        "elevation": 1608.637939453125,
        "location": { "lat": 39.7391536, "lng": -104.9847034 },
        "resolution": 4.771975994110107,
      },
      {
        "elevation": -52.79492568969727,
        "location": { "lat": 36.455556, "lng": -116.866667 },
        "resolution": 19.08790397644043,
      },
    ],
  "status": "OK",
}

XML

<ElevationResponse>
 <status>OK</status>
 <result>
  <location>
   <lat>39.7391536</lat>
   <lng>-104.9847034</lng>
  </location>
  <elevation>1608.6379395</elevation>
  <resolution>4.7719760</resolution>
 </result>
 <result>
  <location>
   <lat>36.4555560</lat>
   <lng>-116.8666670</lng>
  </location>
  <elevation>-52.7949257</elevation>
  <resolution>19.0879040</resolution>
 </result>
</ElevationResponse>

以下範例會要求從加州威特尼市到 Badwater, CA 的直線 path 沿著直線的海拔高度資料。我們要求提供三個 samples，包括兩個端點和半點。

網址

https://maps.googleapis.com/maps/api/elevation/json
  ?path=36.578581%2C-118.291994%7C36.23998%2C-116.83171
  &samples=3
  &key=YOUR_API_KEY

cURL

curl -L -X GET 'https://maps.googleapis.com/maps/api/elevation/json?path=36.578581%2C-118.291994%7C36.23998%2C-116.83171&samples=3&key=YOUR_API_KEY'

JSON

{
  "results":
    [
      {
        "elevation": 4411.94189453125,
        "location": { "lat": 36.578581, "lng": -118.291994 },
        "resolution": 19.08790397644043,
      },
      {
        "elevation": 1372.8359375,
        "location": { "lat": 36.41150289067028, "lng": -117.5602607523847 },
        "resolution": 9.543951988220215,
      },
      {
        "elevation": -84.51690673828125,
        "location": { "lat": 36.23998, "lng": -116.83171 },
        "resolution": 9.543951988220215,
      },
    ],
  "status": "OK",
}

XML

<ElevationResponse>
 <status>OK</status>
 <result>
  <location>
   <lat>36.5785810</lat>
   <lng>-118.2919940</lng>
  </location>
  <elevation>4411.9418945</elevation>
  <resolution>19.0879040</resolution>
 </result>
 <result>
  <location>
   <lat>36.4115029</lat>
   <lng>-117.5602608</lng>
  </location>
  <elevation>1372.8359375</elevation>
  <resolution>9.5439520</resolution>
 </result>
 <result>
  <location>
   <lat>36.2399800</lat>
   <lng>-116.8317100</lng>
  </location>
  <elevation>-84.5169067</elevation>
  <resolution>9.5439520</resolution>
 </result>
</ElevationResponse>