海拔请求
海拔高度 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 的请求会根据请求是针对离散位置还是针对有序路径使用不同的参数。对于离散位置,海拔请求会返回请求中传递的特定位置的数据;对于路径,海拔请求则会在给定路径沿线进行抽样。
依照所有网址的标准,参数都使用“与”符号 (&
) 分隔。下文列出了参数及其可能的值。
所有请求
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
响应。
海拔响应
对于每个有效请求,海拔服务都会以请求网址中指示的格式返回海拔响应。
ElevationResponse
Field | Required | Type | Description |
---|---|---|---|
| required | Array<ElevationResult> | See ElevationResult for more information. |
| required | ElevationStatus | See ElevationStatus for more information. |
| optional | string |
When the service returns a status code other than |
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
Field | Required | Type | Description |
---|---|---|---|
| required | number | The elevation of the location in meters. |
| required | LatLngLiteral | 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. |
| optional | number | 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.
Field | Required | Type | Description |
---|---|---|---|
| required | number | Latitude in decimal degrees |
| required | number | 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>