高度要求和回應

海拔高度要求

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 個字元。建立網址時請注意這項限制。請注意，不同瀏覽器、代理程式和伺服器的網址字元限制也可能不同。

使用 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，Elevation 回應物件中可能會有額外的 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>

以下範例會沿著直線 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>