海拔请求和响应

海拔请求

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 协议。

请求参数

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 时，海拔响应对象中可能还会包含额外的 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>