此页面由 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 对象表示法 (JSON)；或
xml，指示以 XML 格式输出，结果包装在 <ElevationResponse> 节点内。

注意：网址必须编码正确方有效，并且对于所有网络服务，均有 16384 字符数限制。请在构建网址时注意这一限制。请注意，不同的浏览器代理和服务器也可能有不同的网址字符数限制。

对于使用 API 密钥的请求，必须采用 HTTPS 协议。

请求参数

向 Google Elevation API 发出的请求使用不同的参数还是要针对离散位置或有序路径。对于分散位置，海拔请求返回有关请求中所传递具体位置的数据；对于路径，海拔请求则沿给定路径取样。

依照所有网址的标准，参数使用“与”符号 (&) 分隔。参数列表及其可能的值如下所示。

所有请求

key -（必需）应用的 API 密钥。此密钥用于标识您的应用，以便进行配额管理。了解如何获取密钥。

位置请求

locations（必需）：用于指定地球上的具体位置，以便返回所指定位置的海拔数据。此参数采用以英文逗号分隔的 {latitude,longitude} 对表示单个营业地点（例如“40.714728,-73.998672”）或多个纬度/经度对以数组或编码多段线的形式传递。积分上限为 512 点。如需更多信息请参阅下面的指定位置。

抽样路径请求

path（必需）：用于指定地球上的具体路径，以返回该路径的海拔数据。此参数定义一组两个或两个更多有序的 {纬度,经度} 对，定义沿表面的路径此参数必须与下文介绍的 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
使用已编码 Polyline Algorithm：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，海拔响应对象中的 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 上的海拔数据。我们请求获得三个 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