海拔请求和响应

海拔请求

海拔高程 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> 节点内。

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

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

请求参数

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

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

如需了解详情，请参阅 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>