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

产品介绍

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

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

坐标系说明

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(后简称为Place Sug API) 是一套免费使用的API接口,调用次数(配额)与Place API共用,不需要单独申请

使用Place Sug API服务前,首先需要登录API控制台申请密钥ak。

每个开发者账号每天调用Place Sug API服务的总次数(即配额)是有限的。

每个开发者账号每分钟调用Place Sug API服务的次数(即并发量)是有限的。

若需更高配额和并发量,请申请开发者认证以获取更高配额和更及时的技术支持。

同一个帐号下的HTTP/HTTPS请求,配额、并发共享。 默认配额及并发量说明如下:

分类 未认证 个人认证 企业认证
日配额(次) 2,000 30,000 300,000
分钟并发量(次/分钟) 1,200 3,000 12,000

使用方法:

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

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

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

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

Hello, World示例:

发送一个检索关键词为“天安门”的请求,限制返回数据的城市范围为北京市:

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

服务地址

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使用。