高度要求和回應

海拔高度要求

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> 節點。

注意:網址必須是 正確編碼 。 建立網址時,請留意此限制。請注意,不同瀏覽器 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 值。緯度和 經度值必須對應有效的位置 朝地球之路緯度必須是介於 -9090,但經度值可以 -180180 之間的任何值。如果指定 無效的緯度或經度值,系統將拒絕您的要求 視為不良要求

在陣列中,或經過編碼處理的座標,您最多可傳送 512 個座標 ,同時仍在建構有效的網址。 請注意,傳遞多個座標時,任何傳回資料的準確性 的解析度可能低於單一座標的資料。 超過「位置」的 512 個點或座標或「path」參數都會傳回 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 的值。經緯度值必須 然後對應至地球表面的有效位置。緯度必須是介於 -9090,但經度值可以 -180180 之間的任何值。如果指定 無效的緯度或經度值,系統將拒絕您的要求 視為不良要求

在陣列中,或經過編碼處理的座標,您最多可傳送 512 個座標 ,同時仍在建構有效的網址。請注意,傳送多個 座標,任何傳回資料的解析度可能低於 要求單一座標的資料時。超過 512 個點或座標 在「地點」或「path」參數會傳回 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>

以下範例要求沿著直線延伸的海拔高度資料 path從加州惠特尼峰到加州巴特 water,最高價 是美國本土的最低點我們要求提供三個 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>