海拔请求和响应

海拔请求

海拔 API 请求以网址字符串的形式构建。该 API 会返回地球上各个位置的海拔数据。您可以通过以下两种方式之一指定位置数据：

  • 以一组（一个或多个）locations 的形式。
  • 以沿 path 的一系列相连点的形式。

这两种方法都使用纬度/经度坐标来标识位置或路径顶点。本文档介绍了海拔 API 网址所需的格式及可用参数。

海拔 API 会返回单点查询的数据，且精确度尽可能高。涉及多个位置的批量查询可能会返回精确度较低的数据，尤其是在位置分散的情况下，因为系统会对数据进行一些平滑处理。

海拔 API 请求采用以下格式：

https://maps.googleapis.com/maps/api/elevation/outputFormat?parameters

其中，outputFormat 可以是以下任一值：

  • json（推荐），表示以 JavaScript 对象表示法 (JSON) 输出；或
  • xml，表示以 XML 输出，并封装在 <ElevationResponse> 节点内。

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

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

请求参数

对海拔 API 的请求会根据请求是针对离散位置还是针对有序路径而使用不同的参数。对于离散位置，海拔请求会返回请求中传递的特定位置的数据；对于路径，海拔请求则会在给定路径沿线进行抽样。

依照所有网址的标准，参数都使用“与”符号 (&amp;) 分隔。下面列出了参数及其可能的值。

所有请求

  • 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 响应。

海拔响应

  • 一个数组，其中包含两个或更多个以英文逗号分隔的坐标文本字符串，这些字符串使用竖线字符 ('|') 分隔： 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

字段 必需 类型 说明
required Array<ElevationResult> 如需了解详情，请参阅 ElevationResult 。
required ElevationStatus 如需了解详情，请参阅 ElevationStatus 。
可选 字符串

当服务返回的状态代码不是 OK 时，响应对象中可能会包含额外的 error_message 字段。此字段包含有关给定状态代码背后原因的更详细信息 。此字段并非总是返回，并且其内容可能会发生变化。

ElevationStatus

服务返回的状态代码。

  • OK：表示 API 请求成功。
  • DATA_NOT_AVAILABLE ：表示输入的位置没有可用的数据。
  • INVALID_REQUEST：表示 API 请求格式不正确。
  • OVER_DAILY_LIMIT ：表示出现以下任一情况：
    • API 密钥缺失或无效。
    • 您的账号未启用结算功能。
    • 超出了您设定的用量上限。
    • 提供的付款方式不再有效（例如，信用卡已过期）。
  • OVER_QUERY_LIMIT：表示请求者超出了配额。
  • REQUEST_DENIED：表示 API 未完成请求。
  • UNKNOWN_ERROR：表示出现未知错误。

当状态代码不是 OK 时，海拔响应对象中可能会包含额外的 error_message 字段。此字段包含有关给定状态代码背后原因的更详细信息。

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

ElevationResult

字段 必需 类型 说明
required 数值

相应位置的海拔（以米为单位）。
required LatLngLiteral

计算海拔数据时所用地点的 location 元素。请注意，对于路径请求，这组 location 元素将包含路径沿线的抽样点。

如需了解详情，请参阅 LatLngLiteral。

可选 数值

值：表示采用插值法计算海拔时所用数据点之间的最大距离（以米为单位）。 如果分辨率未知，此属性将 缺失。请注意，当传递多个点时，海拔数据会变得更粗糙（分辨率值更大）。如需获取某一点最精确的海拔值，应对其进行独立查询。

LatLngLiteral

一个对象，用于描述具有十进制度纬度和经度的特定位置。

字段 必需 类型 说明
required 数值

纬度（以十进制度为单位）
required 数值

经度（以十进制度为单位）

位置海拔示例

以下示例请求获取科罗拉多州丹佛（“一英里高城”）的海拔：

网址

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>