你现在的位置:首页 > PHP网站建设知识库 > google api > 正文

Google Elevation API

欢迎阅读 Google Elevation API 的开发人员文档!Google Elevation API 为您提供了查询地球上位置的海拔数据的简单接口。此外,您还可以请求对沿途的海拔数据进行抽样,以便计算沿路线的海拔变化。

注意:此 API 不需要 Google Maps API 密钥!

Google Maps API Premier 客户应当用收到的新加密密钥对其网址进行签名。有关详细信息,请参见 Premier 文档。

Google Elevation API 有何用途?

受众
使用限制
海拔请求
输出格式
参数的使用
指定位置
指定路径
指示传感器的使用
海拔响应
位置海拔示例
抽样路径示例
创建海拔图

Google Elevation API 有何用途?

Google Elevation API 提供了地球表面所有位置的海拔数据,包含海底深处位置(传回负值)。在这些情况下,Google 无法提供您请求的确切位置的精确海拔测量值,这项服务将插入并传回四个最近位置的平均值。

借助 Google Elevation API,您可以开发徒步和自行车旅行应用程序、移动定位应用程序或低分辨率测量应用程序。

您可以通过 HTTP 接口访问 Google Elevation API。Google JavaScript API V3 的用户还可以通过使用 ElevationService() 对象直接访问此 API。(有关详情,请参见海拔服务。)

Google Elevation API 是一项新服务,欢迎您加入Google Maps API 论坛,给我们提供反馈。

受众

本文档适用于希望在某个 Google Maps API 提供的地图中使用海拔数据的网站和移动产品开发人员。文中介绍了如何使用 API 以及有关可用参数的参考材料。

使用限制

使用 Google Elevation API 时,每日发送的请求次数不得超过 2,500 次(专业版用户每日最多可以发送 100,000 次请求)。在每个指定的请求中,您最多可以查询 512 个位置的海拔,但每日的查询总数不得超过 25,000 个位置(专业版用户的查询上限为 1,000,000 个位置)。强制执行此限制是为了防止滥用和/或重复使用 Google Elevation API。以后可能对此限制进行更改,而无需另行通知。此外,我们还强制设定了请求速率限制,以防滥用此服务。如果您超出了 24 小时限制或以其他方式滥用此服务,则 Google Elevation API 可能会临时停止运行。如果您继续无视这个限制,将会阻止您对 Google Elevation API 的访问。

对于单点查询,Google Elevation API 会尽可能地传回精确度最高的数据。对于包含多个位置的批量查询,传回的数据精度可能会比较低,尤其是当位置比较分散时,因为过滤掉了某些数据。

此外,在进行网址编码前,请注意 Elevation API 网址长度不得超过 2048 个字符。某些海拔服务网址可能会涉及多个点,因此您在构建网址时请注意此限制。

注意:在使用 Google Elevation API 的同时,必须在 Google Maps 上显示结果。不允许只使用海拔数据而不显示请求海拔数据的地图。有关允许的用法的完整详细信息,请参见 Google Maps API 服务条款许可限制。

海拔请求

Google Elevation API 可传回地球上位置的海拔数据。您可采用以下两种方式之一指定位置数据:

一个或多个 locations 的集合。
沿 path 的一系列连接点。
这两种方式都使用纬度/经度坐标以标识位置或路径顶点。本文档描述了 Google Elevation API 网址的必需格式以及可用的参数。

Google Elevation API 网址必须采用以下形式:

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

提示:您也可以使用 SSL 访问 Google Elevation API,只需将请求网址中的 http 替换为 https 即可。如果应用程序包含敏感的用户数据(例如用户所处位置),推荐在请求中使用 HTTPS。

输出格式

输出格式使用请求网址中末尾的服务标记来指定。Google Elevation API 目前支持以下输出格式:

/json 传回 JavaScript Object Notation (JSON) 形式的结果。
/xml 传回 XML 形式的结果,包含在 <ElevationResponse> 节点中。

参数的用法

Google Elevation API 的请求会根据请求是针对分散位置还是有序路径,使用不同的参数。对于分散的位置,海拔请求会传回请求中所传递的具体位置的数据;对于路径,海拔请求会改为传回沿给定路径的抽样数据。

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

位置请求:

locations(必需)定义要传回海拔数据的地球上的位置。此参数可以是用逗号分隔的 {纬度,经度} 对(如“40.714728,-73.998672”)表示的单个位置,也可以是作为数组或编码折线传递的多个纬度/经度对。有关详细信息,请参见下面的指定位置。

抽样路径请求:

path(必需)定义要传回海拔数据的地球上的路径。此参数定义一组两个或多个有序 {纬度,经度} 对,定义了沿地球表面的路径。此参数必须与下面介绍的 samples 参数配合使用。有关详细信息,请参见下面的指定路径。
samples(必需)指定沿要传回海拔数据的路径的样本点的数量。samples 参数将指定 path 分为一组沿路径的已排序等距点。
报告参数:

sensor(必需)指定请求海拔数据的应用程序是否使用传感器确定用户的位置。所有海拔请求都需要使用此参数。有关详细信息,请参见下面的指示传感器的使用。
指定位置
位置请求采用 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 之间的任何值。如果指定了无效的纬度或经度值,则您的请求将作为错误请求被拒绝。

只要您不超出服务配额,且仍能构造有效网址,您可以在数组或编码折线中传递任意数量的坐标。请注意,如果传递多个坐标,则所有传回数据的分辨率可能会低于请求单个坐标时传回的数据。

指定路径

抽样路径请求采用 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 之间的任何值。如果指定了无效的纬度或经度值,则您的请求将作为错误请求被拒绝。

只要您不超出服务配额,且仍能构造有效网址,您可以在数组或编码折线中传递任意数量的坐标。请注意,如果传递多个坐标,则所有传回数据的分辨率可能会低于请求单个坐标时传回的数据。

指示传感器的使用

使用 Google Elevation API 时,会要求您指明应用程序是否使用传感器(如 GPS 定位器)确定用户的位置。这对移动设备尤为重要。

通过传感器确定用户位置的应用程序必须在海拔 API 请求网址中传递 sensor=true。如果您的应用程序不使用传感器,则传递 sensor=false。

海拔响应

对于每个有效的请求,海拔服务将以请求网址中指定的格式传回海拔响应。每个响应中都将包含以下元素:

海拔 status 代码,可能是以下值之一:   
OK 指示 API 请求成功
INVALID_REQUEST 指示 API 请求错误
OVER_QUERY_LIMIT 指示请求超出了配额
REQUEST_DENIED 指示 API 未完成请求,可能因为请求者没有加入有效的 sensor 参数
UNKNOWN_ERROR 表示未知错误

results 数组包含以下元素:

要计算海拔数据的位置的 location 元素(包含 lat 和 lng 元素)。请注意,对于路径请求,location 元素集将包含沿路径的采样点。
指示位置的海拔的 elevation 元素(以米为单位)。

位置海拔示例

下例请求别名“一里高城”的科罗拉多州丹佛的海拔,采用 JSON 格式:

http://maps.googleapis.com/maps/api/elevation/json?locations=39.7391536,-104.9847034&sensor=true_or_false
{
  "status": "OK",
  "results": [ {
    "location": {
      "lat": 39.7391536,
      "lng": -104.9847034
    },
    "elevation": 1608.8402100
  } ]
}
下例以 JSON 格式显示多个响应(科罗拉多州丹佛和加利福尼亚州死亡谷):

http://maps.googleapis.com/maps/api/elevation/json?locations=39.7391536,-104.9847034|36.455556,-116.866667&sensor=true_or_false
{
  "status": "OK",
  "results": [ {
    "location": {
      "lat": 39.7391536,
      "lng": -104.9847034
    },
    "elevation": 1608.8402100
  }, {
    "location": {
      "lat": 36.4555560,
      "lng": -116.8666670
    },
    "elevation": -50.7890358
  } ]
}
以下请求与上面的第一个示例基本一样,只不过请求使用 /xml 服务标记以指定采用 XML 输出格式。

http://maps.googleapis.com/maps/api/elevation/xml?locations=39.7391536,-104.9847034|36.455556,-116.866667&sensor=true_or_false
<ElevationResponse>
 <status>OK</status> 
 <result> 
  <location> 
   <lat>39.7391536</lat> 
   <lng>-104.9847034</lng> 
  </location> 
  <elevation>1608.8402100</elevation> 
 </result> 
 <result> 
  <location> 
   <lat>36.4555560</lat> 
   <lng>-116.8666670</lng> 
  </location> 
  <elevation>-50.7890358</elevation> 
 </result> 
</ElevationResponse>

路径海拔示例

下例请求沿从加利福尼亚州惠特尼山到坏水盆地的直线 path 的海拔数据,这是美国大陆上的最高点和最低点。我们要求了三个 samples,因此将包含两个端点和一个中途点。

http://maps.googleapis.com/maps/api/elevation/json?path=36.578581,-118.291994|36.23998,-116.83171&samples=3&sensor=true_or_false
{
  "status": "OK",
  "results": [ {
    "location": {
      "lat": 36.5785810,
      "lng": -118.2919940
    },
    "elevation": 4411.9418945
  }, {
    "location": {
      "lat": 36.4115029,
      "lng": -117.5602608
    },
    "elevation": 1381.8616943
  }, {
    "location": {
      "lat": 36.2399800,
      "lng": -116.8317100
    },
    "elevation": -84.6169968
  } ]
}

创建海拔图

在使用海拔数据的同时,必须在 Google Maps 上显示数据。图表 API (http://code.google.com/apis/chart/) 非常适合用于创建海拔图,您可以将海拔图显示在地图旁。

以下 Python 示例计算惠特尼山与死亡谷坏水盆地之间的海拔数据,并使用这些值创建海拔图:

import simplejson
import urllib

ELEVATION_BASE_URL = 'http://maps.googleapis.com/maps/api/elevation/json'
CHART_BASE_URL = 'http://chart.apis.google.com/chart'

def getChart(chartData, chartDataScaling="-500,5000", chartType="lc",chartLabel="Elevation in Meters",chartSize="500x160",chartColor="orange", **chart_args):
    chart_args.update({
      'cht': chartType,
      'chs': chartSize,
      'chl': chartLabel,
      'chco': chartColor,
      'chds': chartDataScaling,
      'chxt': 'x,y',
      'chxr': '1,-500,5000'
    })

    dataString = 't:' + ','.join(str(x) for x in chartData)
    chart_args['chd'] = dataString.strip(',')

    chartUrl = CHART_BASE_URL + '?' + urllib.urlencode(chart_args)

    print chartUrl

    def getElevation(path="36.578581,-118.291994|36.23998,-116.83171",samples="100",sensor="false", **elvtn_args):
      elvtn_args.update({
        'path': path,
        'samples': samples,
        'sensor': sensor
      })

      url = ELEVATION_BASE_URL + '?' + urllib.urlencode(elvtn_args)
      response = simplejson.load(urllib.urlopen(url))

      # Create a dictionary for each results[] object
      elevationArray = []

      for resultset in response['results']:
        elevationArray.append(resultset['elevation'])

      # Create the chart passing the array of elevation data
      getChart(chartData=elevationArray)

if __name__ == '__main__':
    # Mt. Whitney
    startStr = "36.578581,-118.291994"
    # Death Valley
    endStr = "36.23998,-116.83171"

    pathStr = startStr + "|" + endStr

    getElevation(pathStr)