海拔请求
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 协议。
请求参数
向 Google Elevation API 发出的请求使用不同的参数 还是要针对离散位置或 有序路径。对于分散的地点,海拔请求会返回 请求中传递的具体营业地点的相关数据;表示路径, 海拔请求则改为沿指定路径进行抽样。
根据所有网址的标准,参数之间相互分隔
使用和号 (&
) 字符。参数列表
及其可能的值如下所示。
所有请求
key
—(必需)您的应用的 API 密钥。此密钥用于标识您的应用,以便进行配额管理。 了解如何获取密钥。
位置请求
locations
(必需)定义 用于返回海拔数据的地球。此参数采用 以英文逗号分隔的 {latitude,longitude} 对表示单个营业地点 (例如“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
- 使用
已编码
Polyline Algorithm:
locations=enc:gfo}EtohhU
纬度和经度坐标字符串使用数字定义
。例如,“40.714728,-73.998672”
是有效的 locations
值。纬度和
经度值必须对应于有效的位置
纬度可以采用介于
-90
和 90
,而经度值可以为
介于 -180
和 180
之间的任何值。如果您指定
纬度或经度值无效,您的请求将被拒绝
错误请求。
您最多可在一个数组中传递最多 512 个坐标,
同时仍然构造有效网址。
请注意,传递多个坐标时,所返回数据的准确性
分辨率可能低于请求单个坐标数据时的分辨率。
“locations”中的点或坐标超出 512 个或“path”参数会返回
INVALID_REQUEST
响应。
指定路径
抽样路径请求使用 path
进行指示
和 samples
参数,用于表示请求海拔数据
沿某个路径沿特定时间间隔移动。与使用
locations
形参,path
形参会指定
一组纬度和经度值。不过,与位置请求不同的是
path
指定一组有序顶点。而不是返回
海拔数据,路径请求将沿着
路径的长度,基于 samples
的数量
(含端点)。
path
参数可采用下列任一方法
参数:
- 由两个或多个以英文逗号分隔的坐标文本字符串组成的数组
使用竖线(“
|
”)分隔 字符:path=40.714728,-73.998672|-34.397,150.644
- 使用
已编码
Polyline Algorithm:
path=enc:gfo}EtohhUxD@bAxJmGF
纬度和经度坐标字符串使用数字定义
。例如:
“40.714728,-73.998672|-34.397, 150.644”是有效的
path
值。纬度值和经度值必须对应
地球表面上的有效位置。纬度可以采用介于
-90
和 90
,而经度值可以为
介于 -180
和 180
之间的任何值。如果您指定
纬度或经度值无效,您的请求将被拒绝
错误请求。
您最多可在一个数组中传递最多 512 个坐标,
同时仍然构造有效网址。请注意,将多个
坐标时,任何返回数据的精确度可能会低于
。超过 512 个点或坐标
在“locations”中或“path”参数会返回 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>