百度地图的POI帮助文件

1.什么是Place API？

Place API 是一类简单的HTTP接口，用于返回查询某个区域的某类POI数据，且提供单个POI的详情查询服务，用户可以使用C#、C++、Java等开发语言发送HTTP请求且接收json、xml的数据。

2.功能介绍

Place API 提供区域检索POI服务、POI详情服务与团购信息检索服务、商家团购详情查询。

1. 区域检索POI服务提供三种区域检索方法：

城市内检索（对应JavaScriptAPI的Search方法）
矩形检索（对应JavaScript API的SearchInBound方法）
圆形区域检索（对应JavaScript的SearchNearBy方法）。

2. POI详情服务提供查询单个POI的详情信息，如好评。

3. 团购信息检索服务提供三种区域检索方法：

城市内检索
矩形检索
圆形区域检索

4. 商家团购详情查询。

用户可以使用C# 、C++、Java等开发语言发送HTTP请求且接收JSON、XML的返回数据。

3.使用说明

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

ak是API请求串的必填参数，请先获取密钥，若无百度账号则首先需要注册百度账号。

Hello, World

以下是一个关于place API的简单示例，设置检索城市为北京，检索关键字为“饭店”，检索后返回10条数据。

http://api.map.baidu.com/place/v2/search?&q=饭店&region=北京&output=json&ak=E4805d16520de693a3fe707cdc962045

结果说明：点击上述请求url,返回符合检索条件的json格式的数据。

4.Place服务地址

百度地图Place API服务地址：

http://api.map.baidu.com/place/v2/search   //v2 place区域检索POI服务
http://api.map.baidu.com/place/v2/detail   //v2 POI详情服务
http://api.map.baidu.com/place/v2/eventsearch   //v2 团购信息检索服务
http://api.map.baidu.com/place/v2/eventdetail  //v2 商家团购信息查询

组成说明：

域名：http://api.map.baidu.com
服务名：place
服务版本号：较之前版本，v2版本新增参数。
Place方法名：如search表示区域POI查询，detail表示POI详情，eventsearch为团购信息检索，eventdetail为商家团购详情查询。

5.Place区域检索POI服务

5.1 Place区域检索通用接口参数

以下参数，适用于三种区域检索方法的Place API。

参数	是否必须	默认值	格式举例	含义
q(query)	是	无	中关村、ATM、百度大厦	检索关键字，周边检索和矩形区域内检索支持多个关键字并集检索，不同关键字间以$符号分隔，最多支持10个关键字检索。如:”银行$酒店”。
tag	否	无	日式烧烤/铁板烧、朝外大街	标签项，与q组合进行检索
output	否	xml	json或xml	输出格式为json或者xml
scope	是	1	1、2	检索结果详细程度。取值为1 或空，则返回基本信息；取值为2，返回检索POI详细信息
filter	否	无	filter=industry_type:cater\|sort_name:price\|sort_rule:0\|price_section:100,200\|groupon:0\|discount:0	检索过滤条件，当scope取值为2时，可以设置filter进行排序。 industry_type：行业类型注意：设置该字段可提高检索速度和过滤精度。 industry_type取值如下： hotel:宾馆 cater:餐饮 life:生活娱乐 sort_name：排序字段取值根据industry_type字段的值而定。 (1)industry_type为hotel时，sort_name取值： default:默认； price:价格 total_score:好评 level：星级 health_score：卫生 distance:距离排序，只有周边检索有效 (2)industry_type取值cater时，sort_name取值： default：默认 taste_rating：口味 price：价格 overall_rating：好评 service_rating：服务 distance:距离排序，只有周边检索有效 (3)industry_type取值life时，sort_name取值： default：默认 price：价格 overall_rating：好评 comment_num：服务 distance：距离排序，只有周边检索有sort_rule：排序规则，取值如下：0：从高到低，1：从低到高；price_section：价格区间；groupon：是否有团购，1为有团购，0为无团购；discount：是否打折，1为有打折，0为无打折；
page_size	否	10	10	范围记录数量，默认为10条记录，最大返回20条。多关键字检索时，返回的记录数为关键字个数*page_size。
page_num	否	0	0、1、2	分页页码，默认为0,0代表第一页，1代表第二页，以此类推。
ak	是	无	E4805d16520de693a3fe707cdc962045	用户的访问密钥，必填项。v2之前该属性为key。
sn	否	无		用户的权限签名。
timestamp	否	无		设置sn后该值必填。

编码说明：

对于query和region参数，因为这两个参数取值可以是中文或一些特殊字符（如：空格），举例：query可以取值“小吃”，region可以取值“北京”，为了避免提交到后台乱码，所以对于这2个参数值进行编码处理，编码成 UTF-8 字符的二字符十六进制值。 query和region参数取值时候，凡是不在下表中的字符都要进行编码。

字符集合	字符
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保留字	! * ' ( ) ; : @ & = + $ , / ? % # [ ]

如果query和region参数中使用URL保留字字符的字面意思，例如：query关键字取值为"?小吃"，检索关键字包含一个问号，此问号也必须进行编码，"?"的16进制编码为"%3F"，所以整个检索关键字"?小吃"编码后为"%3F%E5%B0%8F%E5%90%83"。

附注：

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

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

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

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

5.2 Place检索示例：

参数	值	说明
query:		检索关键字
scope:		检索结果详细程度。取值为1 或空，则返回基本信息；取值为2，返回检索POI详细信息
page_size:		返回记录数量，默认为10条记录，最大返回结果为20条。
page_num:		分页页码，默认为0,0代表第一页，1代表第二页，以此类推。
region:		检索区域，如果取值为“全国”或某省份，则返回指定区域的POI。

(结果显示如下)

5.3 Place区域检索示例方法

Place API根据支持检索的区域类型，提供城市内、矩形、圆形三种检索方法，使用说明如下：

1）城市内检索请求参数

参数	是否必须	默认值	格式举例	含义
region	是	无	北京、131、全国	检索区域，如果取值为“全国”或某省份，则返回指定区域的POI。

城市检索示例（返回json数据）：

http://api.map.baidu.com/place/v2/search?&query=%E9%93%B6%E8%A1%8C&region=%E6%B5%8E%E5%8D%97&output=json&ak=E4805d16520de693a3fe707cdc962045

2）矩形区域检索参数

参数	是否必须	默认值	格式举例	含义
bounds(bds)	是	无	38.76623,116.43213,39.54321,116.46773 lat,lng(左下角坐标),lat,lng(右上角坐标)	检索矩形区域

矩形检索示例（返回json数据）:

http://api.map.baidu.com/place/v2/search?&query=%E9%93%B6%E8%A1%8C&bounds=39.915,116.404,39.975,116.414&output=json&ak=E4805d16520de693a3fe707cdc962045

3）圆形区域检索参数

参数	是否必须	默认值	格式举例	含义
location	是	无	38.76623,116.43213 lat<纬度>,lng<经度>	周边检索中心点，不支持多个点
radius(r)	否	无	2000	周边检索半径，单位为米

圆形区域检索示例(返回xml数据)：

http://api.map.baidu.com/place/v2/search?&query=%E9%93%B6%E8%A1%8C&location=39.915,116.404&radius=2000&output=xml&ak=E4805d16520de693a3fe707cdc962045

4）Place API检索返回结果字段

状态字段

名称	类型	说明
status	Int	本次API访问状态，如果成功返回0，如果失败返回其他数字。
message	string	对API访问状态值的英文说明，如果成功返回"ok"，并返回结果字段，如果失败返回错误说明。
total	int	检索总数，用户请求中设置了page_num字段才会出现total字段。

结果字段（以结果集合里的一条数据为例，灰色表示扩展字段）：

名称		类型	说明
name		string	poi名称
location		object	poi经纬度坐标
	lat	float	纬度值
	lng	float	经度值
address		string	poi地址信息
telephone		string	poi电话信息
uid		string	poi的唯一标示
detail_info		object	poi的扩展信息，仅当scope=2时，显示该字段，不同的poi类型，显示的detail_info字段不同。
	distance	int32	距离中心点的距离
	type	string	所属分类，如’hotel’、’cater’。
	tag	string	标签
	detail_url	string	poi的详情页
	price	string	poi商户的价格
	shop_hours	string	营业时间
	overall_rating	string	总体评分
	taste_rating	string	口味评分
	service_rating	string	服务评分
	environment_rating	string	环境评分
	facility_rating	string	星级（设备）评分
	hygiene_rating	string	卫生评分
	technology_rating	string	技术评分
	image_num	string	图片数
	groupon_num	int	团购数
	discount_num	int	优惠数
	comment_num	string	评论数
	favorite_num	string	收藏数
	checkin_num	string	签到数

6.Place详情检索服务

服务地址：

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

提供查询某个POI点的详情信息，如好评，评价等。

请求参数说明:

参数	是否必须	默认值	格式举例	含义
uid	是	无	‘8ee4560cf91d160e6cc02cd7’	poi的uid
output	否	xml	json或xml	请求返回格式
scope	是	1	1、2	检索结果详细程度。取值为1 或空，则返回基本信息；取值为2，返回检索POI详细信息
ak	是	无	E4805d16520de693a3fe707cdc962045	用户的访问密钥，必填项。v2之前该属性为key。
sn	否	无		用户的权限签名。
timestamp	否	无		设置sn后该值必填。

返回值与Place API检索返回结果字段相同。

示例：

http://api.map.baidu.com/place/v2/detail?uid=8ee4560cf91d160e6cc02cd7&ak=E4805d16520de693a3fe707cdc962045&output=json&scope=2

返回值：

 
    源码 
    复制 
    打印 
    关于 
   
 {  
     status: 0,  
     message: "ok",  
     result: {  
         name: "江边城外•巫山烤全鱼亚运村店",  
         location: {  
             lng: 116.412347,  
             lat: 40.005328  
         },  
         address: "朝阳区慧忠北路慧忠里123号楼(近北辰东路)",  
         telephone: "(010)64924119",  
         uid: "8ee4560cf91d160e6cc02cd7",  
         detail_info: {  
             tag: "美食 中餐馆 烤鱼 饭统北京 家人团聚 朋友聚会 烧烤 学生聚餐 二三人小聚 家庭团聚 生日PARTY 同事朋友聚会 亚运村店 川菜 适合大伙人 餐馆 川北凉粉 大拌菜 豆豉烤鱼 豆豉清江鱼 怪味清江鱼 会员卡商户 家常泡饼 家庭聚会 可以刷卡 麻辣烤鱼 免费停车 朋友聚餐 皮蛋豆腐 青椒皮蛋 情侣约会 商务宴请 跳水木耳 无线上网 香辣烤鱼 香辣清江鱼 休闲小憩 有无烟区",  
             detail_url: "http://api.map.baidu.com/place/detail?uid=8ee4560cf91d160e6cc02cd7&output=html&source=placeapi_v2",  
             type: "cater",  
             price: "63",  
             overall_rating: "5.0",  
             taste_rating: "5.0",  
             service_rating: "5.0",  
             environment_rating: "5.0",  
             image_num: "671",  
             comment_num: "1191",  
             favorite_num: "1851",  
             checkin_num: "45060",  
             shop_hours: "11：00-23：00"  
         }  
     }  
 }  

7. Place团购检索服务

7.1 团购信息检索服务

服务地址：

http://api.map.baidu.com/place/v2/eventsearch?

根据团购关键字、团购分类、区域范围等条件组合检索，支持按团购价格、距离等条件排序。

请求参数说明:

参数	是否必须	默认值	格式	含义
q(query)	是	无	小吃、宾馆、娱乐	关键字检索
event	是	无	groupon、discount、all	事件名称，可以是团购、打折或全部，目前只支持团购。
region	是	131	北京、131，注意：和search功能不同，此字段必须填写城市名称或城市代码，不能为全国或1。	检索区域
location	是，二选一 1)location 2)bounds 若都出现时，bounds优先级最大，location优先级小。	无	38.76623,116.43213	检索中心点，注意顺序：纬度，经度
radius(r)	否	1000	2000	检索半径。默认1000米，最大可设置2000米。
bounds(bds)	是，二选一 1) location 2) bounds 若都出现时，bounds优先级最大，location优先级小。	无	38.76623,116.43213,39.54321,116.46773	检索矩形Bound，注意顺序：左下角纬度，左下角经度，右上角纬度，右上角经度。
output	否	xml	json或xml，默认xml	输出格式
filter	否	无	检索过滤条件。 groupon_type为团购类型，取值如下： 1: 餐饮 2：生活 3：娱乐 4：旅游住宿 sort_name为排序字段，取值如下： data_type：数据类型，默认排序 groupon_num：团购销量 groupon_price：团购价格 groupon_start：团购开始时间 distance:按距离排序，只对中心点检索有效 sort_rule为排序规则，取值如下： 0: 从高到低 1：从低到高该规则对data_type和groupon_num字段无效。示例： groupon_type:1\|sort_name:group_price\|sort_rule:1
page_size	否	10	10	返回记录数量，默认为10条记录，最大可设置为20条。
page_num	否	0	0、1、2	分页页码，默认为0。 0代表第一页，1代表第二页，以此类推。如果设置了此字段，则输出结果中含有total字段。
ak	是	无	vDh8mxgqaG4clKP7u	用户的访问密钥
sn	否	无	LiD0WoSTit8b8teqHSNysUrK63a3m	用户的权限签名
timestamp	sn存在时必选。	无	1352887837758	时间戳

备注：query和region取值说明详见编码说明。

服务示例:

http://api.map.baidu.com/place/v2/eventsearch?query=%E7%BE%8E%E9%A3%9F&event=groupon&region=131&bounds=39.915,116.404,39.935,116.435&output=json&page_size=1&ak=E4805d16520de693a3fe707cdc962045 //北京市的“美食”团购信息

返回结果：

返回结果有两种形式，一种是json,另一种为xml,默认为xml格式，下面示例为json格式。

 
    源码 
    复制 
    打印 
    关于 
   
 {  
     status: 0,  
     message: "ok",  
     results:   
 [  
     {         
     uid: "9d18c725de1b540efb2d6192",  
     name: "DQ冰淇淋(王府井店)",  
     lcatin:                           
 {             
     lat: "39.920411",  
     lng: "116.418224"                 
 }  
           
     address: "东城区王府井大街138号新东安商场",  
     telephne: "(010)65283613",  
     event:                        
 [  
     {                     
     cn_name: "大众点评",  
     grupn_end: "2013-05-05",  
     grupn_id: "4310671635",  
     grupn_image: "http%3A%2F%2Ftuanimg.baidu.cm%2Fdata%2F2_3b10ad0339b39176869831e787b1a9ea",  
     grupn_num: "38178",  
     grupn_price: "16.6",  
     grupn_rebate: "7.9",  
     grupn_site: : "http%3A%2F%2Ft.dianping.cm%2Fredirect%3Futm_surce%3Dtuan_baidu%26amp%3Bcityname%3Dbeijing",  
     grupn_start: "2013-04-12",  
     grupn_tips:  "< div class="detail-bx"> <h3 class="tit tit-c">特别提示</h3> </br> </br></p class="listitem">有效期：</br>北京地区套餐中杯暴风雪1杯 2013-04-12 至 2013-05-30<br/>天津地区套餐 2013-04-12 至 2013-05-30<《》br/>天津提拉米苏布朗尼套餐 2013-04-14 至 2013-05-30</br/>石家庄地区套餐 2013-04-12 至 2013-05-30</p><p class="listitem">仅限DQ(北京，天津，石家庄)使用，详情见页面附表使用</p><p class="listitem">无需预约</p><p class="listitem">团购券请于到店时出示</p><p class="listitem">不可与其他优惠同享</p><p class="listitem">本单团购不支持退款</p><p class="listitem">本单团购不能使用点评团抵用券/优惠代码</p></br> </br> </div>",   
     grupn_title: "DQ冰淇淋!仅售16.6元,最高价值21元中杯暴风雪1杯!3城97家店可选!缤纷滋味由你决定,倒杯不洒的诱惑,开启甜蜜瞬间!",            
     grupn_type: "1",  
     grupn_url_mbile: "http://tuan.baidu.cm/redirect?frm=bdmapwise&url=http%3A%2F%2Fwap.dianping.cm%2Ftuan%2Fredirect%3Fdid%3D152496",  
     grupn_url_pc:"http://tuan.baidu.cm/redirect?frm=bdmappc&url=http%3A%2F%2Ft.dianping.cm%2Fredirect%3Fdid%3D152496",  
     regular_price: "21",  
     reservatin: "1",  
     shrt_title: "DQ冰淇淋中杯暴风雪冰激凌",  
     spend_end_time: "1369929599"                  
 }  
 ]  
     }  
 ]  
 }  

7.2 商家团购详情查询服务地址：

http://api.map.baidu.com/place/v2/eventdetail?

根据POI UID查询当前POI所有的团购详细信息。

请求参数说明：

参数	是否必须	格式	含义
uid	是	8ee4560cf91d160e6cc02cd7	POI uid
output	否	json或xml	输出格式
ak	必选	vDh8mxgqaG4clKP7u	用户的访问密钥
sn	可选。	LiD0WoSTit8b8teqHSNysUrK63a3m	用户的权限签名
timestamp	sn存在时必选。	1352887837758	时间戳

服务示例:

http://api.map.baidu.com/place/v2/eventdetail?uid=c14fc238f7fadd4ea5da390f&output=json&ak=6cb3f458a482fcd009414370808ea219//根据uid: "c14fc238f7fadd4ea5da390f查询该POI对应的所有团购信息。

返回结果：

返回结果有两种形式，一种是json,另一种为xml,默认为xml格式，下面示例为json格式。

 
    源码 
    复制 
    打印 
    关于 
   
 {  
   
       status: 0,  
       message: "ok",  
       result:   
   
 {  
   
       uid: "c14fc238f7fadd4ea5da390f",  
       name: "觉品壹号",  
       lcatin:  
   
 {  
   
       lat: "39.905745",  
       lng: "116.390223"  
   
 },  
 address: "西城区南新华街1号瑞驰大酒店1楼(近地铁和平门站)",  
 telephne: "(010)63022277,(010)63188187",  
 events:   
 [  
 {  
   
     cn_name: "糯米网",  
     grupn_end: "2013-08-01",  
     grupn_id: "4309423174",  
     grupn_image: "http%3A%2F%2Ftuanimg.baidu.cm%2Fdata%2F2_618fcdeff527f6c3e4af41be48693f4f",  
     grupn_num: "55",  
     grupn_price: "368",  
     grupn_rebate: "2.4",  
     grupn_price: "368",grupn_site: "http%3A%2F%2Fbj.numi.cm",  
     grupn_start: "2013-02-05",<br>  
     grupn_tips:  "1、糯米券有效期为2013年02月05日至2013年08月04日</br>2、营业时间：11:00-14:00；17:00-21:00</br>3、请提前24小时预约，预约电话：010-63188187/13552470897</br>4、糯米券不限购买数量，每张糯米券建议6人使用</br>5、节假日通用（春节、情人节均可以使用）</br>6、糯米券不兑现、不找零，不与店内其他优惠同享",  
     grupn_title: "[觉品壹号会所]6人套餐！创意惊艳岁末宴，春节、假日通用！",  
     grupn_type: "1",  
     grupn_url_mbile: "http://tuan.baidu.cm/redirect?frm=bdmapwise&url=http%3A%2F%2Fm.numi.cm%2Fdeal%2Fview%3Ftinyurl%3D0wua4ryz",  
     grupn_url_pc: "http://tuan.baidu.cm/redirect?frm=bdmappc&url=http%3A%2F%2Fbj.numi.cm%2Fdeal%2F0wua4ryz.html%3Futm_surce%3Dbaidu-cps%26amp%3Butm_medium%3Dny-pic%26amp%3Butm_campaign%3Dny-pic%26amp%3Bcid%3D006001",  
     regular_price: "1558",  
     reservatin: "1",  
     shrt_title: "觉品壹号368",  
     spend_end_time: "1375631999"  
   
 }  
 ]  
 }  
 }  

8.状态码附录

返回码	定义	英文返回描述
0	正常	ok
2	请求参数非法	Parameter Invalid
3	权限校验失败	Verify Failure
4	配额校验失败	Quota Failure
5	ak不存在或者非法	AK Failure
2xx	无权限
3xx	配额错误

9.升级说明

v2版本较之v1版本，功能更新详见更新日志，且请求url参数：新增版本号“v2”，修改“key”为“ak”。V2不兼容v1版本的key，若需升级，请重新获取密钥。
若需查看v1文档，请访问“Place APIv1.0”。