准备工作

在正式进行腾讯地图检索服务开发前请先参考工程设置配置您的工程,并在这里获取开发包。

概述

腾讯地图的检索服务作为一个独立的SDK对外发布,用于访问腾讯地图提供的POI检索、行政区划检索、路线规划等地理信息检索服务。

检索服务SDK需要使用网络,因此至少需要配置网络访问权限:

注意:

由于检索SDK封装了腾讯webservice,因此每key每接口的默认日调用量为1W,并发为5。若用户想增加配额,请根据使用的接口功能按下表选择相应的webservice URL到这里下载模板编辑并发送邮件。注意:请不要将模板作为附件发送,直接编辑模板作为正文发送。

检索服务参数 对应URL
Address2GeoParam /ws/geocoder/v1/?address=*
DistrictChildrenParam /ws/district/v1/list
DrivingParam /ws/direction/v1/driving
Geo2AddressParam /ws/geocoder/v1/?location=*
SearchParam /ws/place/v1/search
StreetViewParam /ws/streetview/v1/getpano
SuggestionParam /ws/place/v1/suggestion
TransitParam /ws/direction/v1/transit
TranslateParam /ws/coord/v1/translate
WalkingParam /ws/direction/v1/walking

使用

检索服务SDK的调用流程主要分以下几步:

1、创建检索服务实例

所有的检索服务都需要检索服务实例提供相应的调用方法。

2、创建检索服务参数实例

不同的检索服务参数对应不同的检索服务功能,下面以地址解析参数的设置为例,更多的参数设置可以参考我们的Demo及文档

3、调用检索服务

检索结果最终由HttpResponseListener提供的回调函数返回,下面依然以地址解析为例:

地址解析及逆地址解析

1、地址解析(地址转坐标)

地址解析,指的是使用位置描述,搜索位置地理坐标信息。如需要查找“北京市海淀区彩和坊路海淀西大街74号”的经纬度坐标,首先构造地址解析参数。

调用TencentSearch.address2geo(Address2GeoParam object, HttpResponseListener listener)方法,在HttpResponseListener.onSuccess(int statusCode, Header[] headers, BaseObject object)回调中获取查询结果:

2、逆地理解析(坐标转地址)

逆地址解析,指的是使用经纬度坐标,搜索该坐标的位置描述,包括该坐标点所在地的地理位置,行政区划信息,和POI信息。例如,想获取坐标点(39.984154,116.307490)的位置信息,检索参数的构造如下所示。

调用TencentSearch.geo2address(Geo2AddressParam object, HttpResponseListener listener)方法,在HttpResponseListener.onSuccess(int statusCode, Header[] headers, BaseObject object)回调中获取查询结果:

POI检索

POI搜索,主要提供了城市内关键字搜索,周边(圆形范围)搜索,矩形框搜索,并且可以把搜索结果在MapView上标注。

1、城市关键字检索

可以通过设置城市名称和搜索关键字,进行城市内搜索。例如,在北京市内搜索银行,代码如下所示。

调用TencentSearch.search(SearchParam object, HttpResponseListener listener)方法,在HttpResponseListener.onSuccess(int statusCode, Header[] headers, BaseObject object)回调中获取查询结果:

POI检索每次查询只返回一页数据,如果要多页POI数据,则需要进行多次查询,使用page_index(int)设置查询的页码,该接口默认页码是第一页(值为1),使用page_size(int)设置每页返回的POI个数,该接口最大限制20个。例如,如果要查询第3页POI数据,代码如下所示。

2、周边(圆形范围)搜索

周边搜索,即圆形搜索,在一个圆形范围内,根据设定的半径进行关键字搜索。比如,在坐标点(39.917237,116.39757)1000米范围内搜索银行,示例代码如下所示。

3、矩形范围搜索

在一个矩形范围内,根据设定的半径进行关键字搜索。比如,在坐标点(39.923462,116.389418)和(39.912995,116.403837)之间搜索故宫,示例代码如下所示。

4、POI点的标注

使用SearchParam类进行了搜索后,可以使用SearchResultObject获取查询结果列表,通过访问每个SearchResultData,然后使用Marker进行POI点的标注。

添加到MapView后,POI标注如下图所示。

关键字提示

用于获取输入关键字的补完与提示,帮助用户快速输入。

调用TencentSearch.suggestion(SuggestionParam object, HttpResponseListener listener)方法,在HttpResponseListener.onSuccess(int statusCode, Header[] headers, BaseObject object)回调中获取查询结果:

  • Tips
  • 用户可以使用用ListView完成智能提示的交互功能

    行政区划

    用于获取中国标准行政区划数据,可以在生成城市列表控件等功能时使用

    调用TencentSearch.getDistrictChildren(DistrictChildrenParam object, HttpResponseListener listener)方法,在HttpResponseListener.onSuccess(int statusCode, Header[] headers, BaseObject object)回调中获取查询结果:

    街景场景信息查询

    街景场景信息查询可以根据指定坐标及半径,查询该坐标所在位置附近的最近场景点,返回场景点ID等信息。

    调用TencentSearch.getDistrictChildren(DistrictChildrenParam object, HttpResponseListener listener)方法,在HttpResponseListener.onSuccess(int statusCode, Header[] headers, BaseObject object)回调中获取查询结果:

    坐标转换

    用于从其它地图供应商坐标系或标准GPS坐标系,批量转换到腾讯地图坐标系。

    调用TencentSearch.translate(TranslateParam object, HttpResponseListener listener)方法,在HttpResponseListener.onSuccess(int statusCode, Header[] headers, BaseObject object)回调中获取查询结果:

    路线规划

    检索服务包还提供了路线规划服务,包括步行、驾车和公交换乘方案的规划。

    1、步行方案规划服务

    步行方案规划使用WalkingParam设置步行检索参数,查询输入参数为起点,终点,代码如下所示。

    调用TencentSearch.getDirection(RoutePlanningParam param, HttpResponseListener listener)方法,在HttpResponseListener.onSuccess(int statusCode, Header[] headers, BaseObject object)回调中获取查询结果:

    返回结果中的routes字段是一个List,表明结果可能有多条路线,其元素类型为WalkingResultObject.Route,包含了这条路线的方向、距离、所需时间、路线点串(用于在地图画出路线),以及分段的路线计划steps。

    steps也是一个List,其元素类型为RoutePlanningObject.Step,该类提供了用于导航的信息,这些信息的分析如下:

    • RoutePlanningObject.Step.accessorial_desc 本段的附加信息,可能为空,如“进入北四环西路”
    • RoutePlanningObject.Step.act_desc 本段的动作,如“右转”
    • RoutePlanningObject.Step.dir_desc 本段的方向,如“北”
    • RoutePlanningObject.Step.distance 本段的长度,单位:米
    • RoutePlanningObject.Step.duration 本段的用时,单位:分钟
    • RoutePlanningObject.Step.instruction 腾讯提供的本段的默认信息,如“向北步行100m,右转进入北四环西路”
    • RoutePlanningObject.Step.polyline_idx 本段的起点和终点在点串中的位置
    • RoutePlanningObject.Step.road_name 本段的路名,如“彩和坊路”

    2、驾车路线规划服务

    驾车线路规划使用DrivingParam设置驾车检索参数,支持设置搜索策略,如快捷、距离短、不走高速等;支持途经点设置,示例代码如下所示。

    调用TencentSearch.getDirection(RoutePlanningParam param, HttpResponseListener listener)方法,在HttpResponseListener.onSuccess(int statusCode, Header[] headers, BaseObject object)回调中获取查询结果:

    驾车规划的返回数据中除了增加了途经点,其他数据结构和步行是一致的,可以完全参考步行的分析。

    3、公交换乘方案规划服务

    可以使用RouteSearch进行公交换乘方案查询,可以设置搜索策略,如快捷、少换乘、少步行,查询输入参数为城市起点、终点,代码如下所示。

    调用TencentSearch.getDirection(RoutePlanningParam param, HttpResponseListener listener)方法,在HttpResponseListener.onSuccess(int statusCode, Header[] headers, BaseObject object)回调中获取查询结果:

    在返回结果中的routs字段是以TransitResultObject.Route为模板的List列表,包含的换乘的多种方案。这个类包含每种方案在地图上的范围:bounds;每种方案的距离和预计用时;以及每种方案的具体换乘信息:steps。steps字段是以TransitResultObject.Segment为模板的List列表,TransitResultObject.Segment类是TransitResultObject.Walking和TransitResultObject.Transit两个类的父类。因为具体的换乘信息可能包含步行路段和乘车路段,这样才能获取完整的换乘信息。所以在解析steps字段的时候,需要判断每个元素的具体类型,才能进行正确的解析。TransitResultObject.Walking这个类的解析和步行的规划结果是类似的,下面只分析一下TransitResultObject.Transit类。

    TransitResultObject.Transit类包含lines字段,List列表模板是TransitResultObject.Line类,这个类用于表示方案中换乘的公共交通线路的信息,包含:

    • TransitResultObject.Line.destination 终点站,用于表示乘坐线路的方向
    • TransitResultObject.Line.distance 距离,单位:米
    • TransitResultObject.Line.duration 估计用时,单位:分钟
    • TransitResultObject.Line.getoff TransitResultObject.GetOnOrOff类型表示站点,包含坐标位置location和站名title
    • TransitResultObject.Line.geton TransitResultObject.GetOnOrOff类型表示站点,包含坐标位置location和站名title
    • TransitResultObject.Line.id 线路ID
    • TransitResultObject.Line.polyline 路线的坐标点串,用于将线路绘制到地图上,需要注意的是这个只需要取lines中的第一个元素。比如在公交路线中,两个站点间有多条线路选择,且走的路线是相同的,就会被归于同一个lines列表中。
    • TransitResultObject.Line.station_count 本线路中经过的站点数目
    • TransitResultObject.Line.title 线路名称,如“1”、“地铁1号线”等
    • TransitResultObject.Line.vehicle 线路类型,“RAIL”,“BUS”,“SUBWAY”三者之一

    下面是Demo中公交规划的截图: