目录
Place API V2.0
Place APIv1.0 访问入口 自2014年9月1日起，我们将废弃Place API v1.0。届时 Place API v1.0将无法正常使用。
什么是Place API？
Place API 是一类简单的HTTP接口，用于返回查询某个区域的某类POI数据，且提供单个POI的详情查询服务，用户可以使用C#、C++、Java等开发语言发送HTTP请求且接收json、xml的数据。
功能介绍
Place API 提供区域检索POI服务、POI详情服务与团购信息检索服务、商家团购详情查询。
1. 区域检索POI服务提供三种区域检索方法：
城市内检索（对应JavaScriptAPI的Search方法）
矩形检索（对应JavaScript API的SearchInBound方法）
圆形区域检索（对应JavaScript的SearchNearBy方法）。
2. POI详情服务提供查询单个POI的详情信息，如好评。
3. 团购信息检索服务提供三种区域检索方法：
城市内检索
矩形检索
圆形区域检索
4. 商家团购详情查询。
用户可以使用C# 、C++、Java等开发语言发送HTTP请求且接收JSON、XML的返回数据。
使用说明
Place API 是一套免费使用的API接口，调用次数限制为10万次/天。
ak是API请求串的必填参数，请先获取密钥，若无百度账号则首先需要注册百度账号。
Hello, World
以下是一个关于place API的简单示例，设置检索城市为北京，检索关键字为“饭店”，检索后返回10条数据。
结果说明：点击上述请求url,返回符合检索条件的json格式的数据。
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 商家团购信息查询
组成说明：
域名：api.map.baidu.com
服务名：place
服务版本号：较之前版本，v2版本新增参数。
Place方法名：如search表示区域POI查询，detail表示POI详情，eventsearch为团购信息检索，eventdetail为商家团购详情查询。
Place区域检索POI服务
服务地址：
http://api.map.baidu.com/place/v2/search
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:distance|sort_rule:1 | 检索过滤条件，当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 | 是 | 无 | 用户的访问密钥，必填项。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对特殊字符进行编码。
Place检索示例：
Place区域检索示例方法
Place API根据支持检索的区域类型，提供城市内、矩形、圆形三种检索方法，使用说明如下：
城市内检索请求参数
| 参数 | 是否必须 | 默认值 | 格式举例 | 含义 |
|---|---|---|---|---|
| region | 是 | 无 | 北京、131、全国 | 检索区域（市级以上行政区域），如果取值为“全国”或某省份，则返回指定区域的POI及数量。 |
城市检索示例（返回json数据）：
矩形区域检索参数
| 参数 | 是否必须 | 默认值 | 格式举例 | 含义 |
|---|---|---|---|---|
| bounds(bds) | 是 | 无 | 38.76623,116.43213,39.54321,116.46773 lat,lng(左下角坐标),lat,lng(右上角坐标) | 检索矩形区域 |
矩形检索示例（返回json数据）:
圆形区域检索参数
| 参数 | 是否必须 | 默认值 | 格式举例 | 含义 |
|---|---|---|---|---|
| location | 是 | 无 | 38.76623,116.43213
lat<纬度>,lng<经度> |
周边检索中心点，不支持多个点 |
| radius(r) | 否 | 无 | 2000 | 周边检索半径，单位为米 |
圆形区域检索示例(返回xml数据)：
Place API检索返回结果字段
状态字段
| 名称 | 类型 | 说明 |
|---|---|---|
| status | Int | 本次API访问状态，如果成功返回0，如果失败返回其他数字。 |
| message | string | 对API访问状态值的英文说明，如果成功返回"ok"，并返回结果字段，如果失败返回错误说明。 |
| total | int | 检索总数，用户请求中设置了page_num字段才会出现total字段。当检索总数值大于760时，多次刷新同一请求得到total的值可能稍有不同，属于正常情况。 |
结果字段（以结果集合里的一条数据为例，灰色表示扩展字段）：
| 名称 | 类型 | 说明 | |
|---|---|---|---|
| name | string | poi名称 | |
| location | object | poi经纬度坐标 | |
| lat | float | 纬度值 | |
| lng | float | 经度值 | |
| address | string | poi地址信息 | |
| telephone | string | poi电话信息 | |
| uid | string | poi的唯一标示 | |
| street_id | string | 街景图id | |
| detail | string | 是否有详情页：1有，0没有 | |
| 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 | 签到数 | |
Place详情检索服务
服务地址：
http://api.map.baidu.com/place/v2/detail
提供查询某个POI点的详情信息，如好评，评价等。
请求参数说明:
| 参数 | 是否必须 | 默认值 | 格式举例 | 含义 |
|---|---|---|---|---|
| uid | 是 | 无 | ‘8ee4560cf91d160e6cc02cd7’ | poi的uid |
| uids | 是 | 无 | ‘8ee4560cf91d160e6cc02cd7’,‘5ffb1816cf771a226f476058’ | uid的集合，最多可以传入10个uid，多个uid之间用英文逗号分隔。 |
| output | 否 | xml | json或xml | 请求返回格式 |
| scope | 是 | 1 | 1、2 | 检索结果详细程度。取值为1 或空，则返回基本信息；取值为2，返回检索POI详细信息 |
| ak | 是 | 无 | E4805d16520de693a3fe707cdc962045 | 用户的访问密钥，必填项。v2之前该属性为key。 |
| sn | 否 | 无 | 用户的权限签名。 | |
| timestamp | 否 | 无 | 设置sn后该值必填。 |
返回值与Place API检索返回结果字段相同。
服务示例：
返回值：
{ "status": 0, "message": "ok", "result": { "name": "百度大厦员工食堂", "location": { "lng": 116.308022, "lat": 40.056892 }, "address": "海淀区上地十街10号(近辉煌国际)", "detail": 1, "uid": "5a8fb739999a70a54207c130", "detail_info": { "tag": "美食;其他", "detail_url": "http://api.map.baidu.com/place/detail?uid=5a8fb739999a70a54207c130&output=html&source=placeapi_v2", "type": "cater", "price": "11.0", "overall_rating": "4.0", "taste_rating": "4.0", "service_rating": "4.0", "environment_rating": "4.0", "image_num": "2", "comment_num": "8", "shop_hours": "早9点到晚8点", "atmosphere": "", "featured_service": "", "recommendation": "麻辣烫,烤鱼", "description": "门店介绍：" } } }
Place团购检索服务
团购信息检索服务
服务地址：
http://api.map.baidu.com/place/v2/eventsearch
根据团购关键字、团购分类、区域范围等条件组合检索，支持按团购价格、距离等条件排序。
请求参数说明:
| 参数 | 是否必须 | 默认值 | 格式 | 含义 |
|---|---|---|---|---|
| q(query) | 是 | 无 | 小吃、宾馆、娱乐 | 关键字检索 |
| event | 是 | 无 | groupon、discount、all | 事件名称，可以是团购、打折或全部，目前只支持团购。 |
| region | 是 | 131 | 北京、131，注意：和search功能不同，此字段必须填写城市名称或城市代码，不能为全国或1。 | 检索区域 |
| location | 是，location或bounds二选一：若都出现时，bounds优先级最大，location优先级小。 | 无 | 38.76623,116.43213 | 检索中心点，注意顺序：纬度，经度 |
| radius(r) | 否 | 1000 | 2000 | 检索半径。默认1000米，最大可设置2000米。 |
| bounds(bds) | 是，location或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:按距离排序，只对中心点检索有效
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取值说明详见编码说明。
服务示例:
bounds检索(json)示例:
location检索（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" } ] } ] }
商家团购详情查询
服务地址：
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 | 时间戳 |
服务示例:
返回结果： 返回结果有两种形式，一种是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", 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" } ] } }
状态码附录
| 返回码 | 定义 | 英文返回描述 |
|---|---|---|
| 0 | 正常 | ok |
| 2 | 请求参数非法 | Parameter Invalid |
| 3 | 权限校验失败 | Verify Failure |
| 4 | 配额校验失败 | Quota Failure |
| 5 | ak不存在或者非法 | AK Failure |
| 2xx | 无权限 | |
| 3xx | 配额错误 |
升级说明
v2版本较之v1版本，功能更新详见更新日志，且请求url参数：新增版本号“v2”，修改“key”为“ak”。V2不兼容v1版本的key，若需升级，请重新获取密钥。
若需查看v1文档，请访问“Place APIv1.0”。