高度要求和回應

海拔高度要求

Elevation API 要求會以網址字串的形式建構。這個 API 會傳回地球上各個位置的海拔高度資料。您可以使用下列任一方式指定位置資料：

  • 以一或多個 locations 組成的集合。
  • 沿著 path 連接的一系列點。

這兩種方法都會使用經緯度座標來識別位置或路徑頂點。本文說明 Elevation API 網址的必要格式和可用的參數。

Elevation API 會傳回單點查詢的資料，且精確度會盡可能提高。涉及多個地點的批次查詢可能會傳回準確度較低的資料，尤其是如果地點分散，資料會經過一些平滑處理。

Elevation API 要求採用下列格式：

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

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

  • json (建議使用) 表示輸出內容格式為 JavaScript 物件標記法 (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 格式的「Mile High City」：

網址

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>

以下範例要求從加州惠特尼山 (Mt. Whitney, 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>