高度要求和回應

海拔高度要求

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 的要求會根據要求是針對不連續位置還是有序路徑，使用不同的參數。如果是不連續的位置，海拔高度要求會針對已傳入要求中的特定位置傳回資料；如果是路徑，海拔高度要求則會在指定路徑沿途中「取樣」。

依照所有網址的標準，這裡的參數都會以 & 字元分隔。以下列出參數清單和可能的值。

所有要求

• 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 回應。

海拔高度回應

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

如果狀態碼不是 OK，海拔高度回應物件可能會包含額外的 error_message 欄位。這個欄位會提供更多詳細資訊，說明指定狀態碼的原因。

回應會包含含有下列元素的 results 陣列：

location 物件包含下列元素：

位置提升範例

以下範例會要求科羅拉多州丹佛的海拔高度，採用 JSON 格式的「Mile High City」：

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

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

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

<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 -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 回應範例。

{
  "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",
}

<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 -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'

{
  "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",
}

<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>