海拔高度要求
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 發出的要求會使用不同的參數,視要求為獨立位置或已排序路徑而定。如果是不連續的位置,海拔高度要求會針對已傳入要求中的特定位置傳回資料;如果是路徑,海拔高度要求會沿著指定路徑「取樣」。
如同所有網址,這裡的參數都會以 &
字元分隔。參數清單及其可能的值表示如下。
所有要求
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
Field | Required | Type | Description |
---|---|---|---|
| required | Array<ElevationResult> | See ElevationResult for more information. |
| required | ElevationStatus | See ElevationStatus for more information. |
| optional | string |
When the service returns a status code other than |
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
Field | Required | Type | Description |
---|---|---|---|
| required | number | The elevation of the location in meters. |
| required | LatLngLiteral | 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. |
| optional | number | 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.
Field | Required | Type | Description |
---|---|---|---|
| required | number | Latitude in decimal degrees |
| required | number | 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>