海拔请求和响应

海拔请求

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，表示封装在 <ElevationResponse> 节点中的 XML 输出。

注意：网址必须正确编码才能有效，并且所有网络服务的网址长度不得超过 16384 个字符。构建网址时，请注意此限制。请注意，不同的浏览器、代理和服务器对网址字符数的限制也可能不同。

对于使用 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 响应。

海拔响应

对于每个有效请求，海拔服务均会以请求网址中指明的格式返回海拔响应。

如果状态代码不是 OK，则 Elevation 响应对象中可能还有一个 error_message 字段。此字段包含有关给定状态代码背后原因的更详细信息。

响应包含一个 results 数组，其中包含以下元素：

location 对象包含以下元素：

位置海拔示例

以下示例以 JSON 格式请求科罗拉多州丹佛市的海拔高度（又称“海拔一英里城市”）：

https://maps.googleapis.com/maps/api/elevation/json
  ?locations=39.7391536%2C-104.9847034
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/elevation/json?locations=39.7391536%2C-104.9847034&key=YOUR_API_KEY'

{
  "results":
    [
      {
        "elevation": 1608.637939453125,
        "location": { "lat": 39.7391536, "lng": -104.9847034 },
        "resolution": 4.771975994110107,
      },
    ],
  "status": "OK",
}

<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 -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 响应示例。

{
  "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",
}

<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 -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'

{
  "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",
}

<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>