海拔请求和响应

海拔请求

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 请求会根据请求是针对分散的位置还是有序路径来使用不同的参数。对于分散的位置,海拔请求会返回请求中传递的特定位置的相关数据;对于路径,海拔请求会改为沿指定路径进行采样

根据所有网址的标准,参数使用和号字符 (&amp;) 进行分隔。下面列出了各个参数及其可能的值。

所有要求

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

位置请求

  • locations(必需)定义地球上要返回海拔数据的位置。此参数采用英文逗号分隔的 {纬度,经度} 对形式(例如“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 值。纬度和经度值必须与地球表面上的有效位置相对应。纬度可以是 -9090 之间的任何值,而经度值可以是 -180180 之间的任何值。如果您指定的纬度或经度值无效,您的请求将作为错误请求而被拒绝。

您可以在数组或编码多段线中传递最多 512 个坐标,同时仍会构建有效网址。请注意,传递多个坐标时,与请求单个坐标的数据时相比,所返回的任何数据的分辨率可能较低。“locations”或“path”参数中超过 512 个点或坐标时,系统会返回 INVALID_REQUEST 响应。

指定路径

抽样路径请求采用 pathsamples 参数表示,用于指定沿着指定间隔的路径的海拔数据请求。与使用 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 值。纬度和经度值必须与地球表面上的有效位置相对应。纬度可以是 -9090 之间的任何值,而经度值可以是 -180180 之间的任何值。如果您指定的纬度或经度值无效,您的请求将作为错误请求而被拒绝。

您可以在数组或编码多段线中传递最多 512 个坐标,同时仍会构建有效网址。请注意,传递多个坐标时,返回的任何数据的分辨率可能低于请求单个坐标的数据时分辨率。如果“locations”或“path”参数中超过 512 个点或坐标,则会返回 INVALID_REQUEST 响应。

海拔响应

对于每个有效请求,海拔服务都将以请求网址内指定的格式返回海拔响应。

ElevationResponse

FieldRequiredTypeDescription
required Array<ElevationResult> See ElevationResult for more information.
requiredElevationStatus See ElevationStatus for more information.
optionalstring

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

FieldRequiredTypeDescription
requirednumber

The elevation of the location in meters.

requiredLatLngLiteral

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.

optionalnumber

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.

FieldRequiredTypeDescription
requirednumber

Latitude in decimal degrees

requirednumber

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>