您当前的位置: Web服务API > Place Suggestion API
Place Suggestion API

产品介绍

Place suggestion API 是一套提供匹配用户输入关键字辅助信息、提示服务的接口,可返回json或xml格式的一组建议词条的数据。

Place suggestion API 已全面支持HTTP/HTTPS两种请求形式。后文介绍中以HTTP请求为例。

该套API免费对外开放,您需先申请密钥(ak) ,1个ak支持10万次/天。

坐标系说明

WGS84:为一种大地坐标系,也是目前广泛使用的GPS全球卫星定位系统使用的坐标系。


GCJ02:是由中国国家测绘局制订的地理信息系统的坐标系统。由WGS84坐标系经加密后的坐标系。


BD09:为百度坐标系,在GCJ02坐标系基础上再次加密。其中bd09ll表示百度经纬度坐标,bd09mc表示百度墨卡托米制坐标


Place Suggestion API默认输入输出坐标类型为百度坐标(BD09),同时可通过参数("coord_type","ret_coordtype")控制输入输出坐标类型。

输入坐标支持以上三种坐标系,输出坐标支持-国测局坐标(GCJ02)和百度坐标(BD09)


注意:不同类型坐标如需转换,请使用百度地图开放平台提供的标准坐标转换接口。请勿使用其他渠道提供的坐标转换方法,以免影响坐标转换精度。

适用场景

配合Place API使用:使用本接口请求,可调出匹配用户输入的关键字的建议列表,用户选择列表中确定的一条,结合Place API返回查询的结果。效果如下:

place-suggest.jpg

使用说明

使用限制:

Place Suggestion API 是一套免费使用的API接口,调用次数限制为10万次/天。

同一个帐号下的HTTP/HTTPS请求,配额、并发共享。

使用方法:

第一步,申请密钥(ak) ,作为访问服务的依据;

第二步,按照请求参数说明拼写发送HTTP/HTTPS请求的url,注意需使用第一步申请的ak;

第三步,接收返回的数据(json或xml格式)。

注:本接口不支持回调,如需在JavaScript中回调使用,可以直接参考JavaScript API封装的Suggestion函数,体验效果

服务地址

http://api.map.baidu.com/place/v2/suggestion/

请求接口参数

参数名称 是否必须 默认值 格式 备注
q(query) 上地、天安、中关、shanghai 输入建议关键字(支持全拼检索)
region 全国、北京市、131、江苏省等 支持全国、省、城市及对应百度编码(citycode)。(指定的区域的返回结果加权,可能返回其他城市高权重结果。若要对返回结果区域严格限制,请使用city_limit参数)
city_limit false "false"or"true" 取值为"true",仅返回region中指定城市检索结果
location 40.047857537164,116.31353434477 传入location参数后,返回结果将以距离进行排序
ret_coordtype gcj02ll 可选参数,添加后POI返回国测局经纬度坐标
output xml json、xml 返回数据格式,可选json、xml两种
ak E4805d16520de693a3fe707cdc962045 开发者访问密钥,必选。
sn 用户的权限签名
timestamp 设置sn后该值必选

编码说明:

API请求中需要用到中文或一些特殊字符的参数,如query、region等,为了避免提交到后台乱码,需要对这几个参数值进行编码处理,转换成UTF-8字符的二字符十六进制值,凡是不在下表中的字符都需要进行编码。

字符集合 字符
URL非保留字 a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 7 8 9 - _ . ~
URL保留字 ! * ' ( ) ; : @ & = + $ , / ? % # [ ]

如果中文参数中使用URL保留字字符的字面意思,例如:region关键字取值为"?北京",检索关键字包含一个问号,此问号也必须进行编码。

附注:

(1) javascript中一般采用encodeURIComponent函数对特殊字符进行编码。

(2) Java中可以使用函数URLEncoder.encode对特殊字符进行编码。

(3) C#中可以使用函数HttpUtility.UrlEncode对特殊字符进行编码。

(4) php中可以使用函数urlencode对特殊字符进行编码。

返回值

状态字段

名称 类型 说明
status Int 本次API访问状态,如果成功返回0,如果失败返回其他数字。
message string 对API访问状态值的英文说明,如果成功返回"ok",并返回结果字段,如果失败返回错误说明。

结果字段

名称 类型 说明
name string poi名称
location object poi经纬度坐标
uid string poi的唯一标示,ID
city string 城市
district string 区县

接口示例

服务示例:返回一组包含"天安门"字段的建议词条列表

http://api.map.baidu.com/place/v2/suggestion?query=天安门&region=北京市&city_limit=true&output=json&ak=您的密钥ak

说明:

query是需要查询输入建议的关键字,region是指定辅助城市,output用于指定返回数据的格式(xml或json);ak是开发者请求数据的标识。

返回结果:

 
{
    "status":0,
    "message":"ok",
    "result":[
        {
            "name":"天安门",
            "location":{
                "lat":39.915174,
                "lng":116.403875
            },
            "uid":"65e1ee886c885190f60e77ff",
            "city":"北京市",
            "district":"东城区",
        },
        {
            "name":"天安门广场",
            "location":{
                "lat":39.912735,
                "lng":116.404015
            },
            "uid":"c9b5fb91d49345bc5d0d0262",
            "city":"北京市",
            "district":"东城区",
        },
        ...
    ]
}

更新日志

2015年4月22日加入地理位置属性的查询

2013年7月5日Place suggestion API v1.0发布。

产品上线:新增获取关键字提示词条的数据接口,配合Place API使用。