本頁面由 Cloud Translation API 翻譯而成。

高度要求和回應

海拔高度要求

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> 節點中包裝。

注意：網址必須是正確編碼。建立網址時請注意這項限制。請注意，不同瀏覽器、代理程式和伺服器的網址字元限制也可能不同。

使用 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
`results`	required	Array<ElevationResult>	See ElevationResult for more information.
`status`	required	ElevationStatus	See ElevationStatus for more information.
`error_message`	optional	string	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

Field	Required	Type	Description
`elevation`	required	number	The elevation of the location in meters.
`location`	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.
`resolution`	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
`lat`	required	number	Latitude in decimal degrees
`lng`	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>

以下範例要求沿著直線延伸的海拔高度資料 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>

高度要求和回應

海拔高度要求

要求參數

所有要求

位置要求

取樣路徑要求

指定位置

指定路徑

海拔高度回應

ElevationResponse

`results`

`status`

`error_message`

ElevationStatus

ElevationResult

`elevation`

`location`

`resolution`

LatLngLiteral

`lat`

`lng`

位置提升範例

網址

cURL

JSON

XML

網址

cURL

JSON

XML

網址

cURL

JSON

XML