您当前的位置: Web服务API > 开发指南 > Place API
Place API

产品介绍

Place API 是一类简单的接口,用于返回查询某个区域的某类POI数据,且提供单个POI的详情查询服务,用户可以使用C#、C++、Java等开发语言发送请求且接收json、xml的数据。
Place API 已全面支持HTTP/HTTPS两种请求形式。后文介绍中以HTTP请求为例。

坐标系说明

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


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


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


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

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


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

功能介绍

Place API 提供区域检索POI服务与POI详情服务。

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

城市内检索(对应JavaScriptAPI的Search方法)

矩形检索(对应JavaScript API的SearchInBound方法)

圆形区域检索(对应JavaScript的SearchNearBy方法)。

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

使用说明

使用限制:

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

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

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

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

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

默认配额及并发量说明如下:

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

Hello, World示例:

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

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

Place服务地址

百度地图Place API服务地址:

http://api.map.baidu.com/place/v2/search //v2 place区域检索POI服务
 
http://api.map.baidu.com/place/v2/detail //v2 POI详情服务

组成说明:

域名:api.map.baidu.com

服务名:place

服务版本号:较之前版本,v2版本新增参数。

Place方法名:如search表示区域POI查询,detail表示POI详情。

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:行业类型,注意:设置该字段可提高检索速度和过滤精度,取值有: 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(无)

coord_type 3 1、2、3、4

坐标类型,1(wgs84ll即GPS经纬度),2(gcj02ll即国测局经纬度坐标),3(bd09ll即百度经纬度坐标),4(bd09mc即百度米制坐标)

ret_coordtype gcj02ll

可选参数,添加后POI返回国测局经纬度坐标

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检索示例:

城市内检索

http://api.map.baidu.com/place/v2/search?query=银行&page_size=10&page_num=0&scope=1&region=北京&output=json&ak={您的密钥}

矩形区域检索

http://api.map.baidu.com/place/v2/search?query=美食&page_size=10&page_num=0&scope=1&bounds=39.915,116.404,39.975,116.414&output=json&ak={您的密钥}

圆形区域检索

http://api.map.baidu.com/place/v2/search?query=酒店&page_size=10&page_num=0&scope=1&location=39.915,116.404&radius=2000&output=json&ak={您的密钥}
 
//多关键词并集检索
http://api.map.baidu.com/place/v2/search?query=酒店$银行&scope=2&output=json&location=39.915,116.404&radius=2000&filter=sort_name:distance|sort_rule:1&ak={您的密钥}

Place区域检索示例方法

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

城市内检索请求参数

参数 是否必须 默认值 格式举例 含义
region 北京、131、全国 检索区域(市级以上行政区域),如果取值为“全国”或某省份,则返回指定区域的POI及数量。
city_limit false 是否只返回指定region(城市)内的POI,true(是),false(否)。

城市检索示例(返回json数据):

http://api.map.baidu.com/place/v2/search?query=百度大厦&region=深圳&city_limit=true&output=json&ak={您的密钥}

矩形区域检索参数

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

矩形检索示例(返回json数据):

http://api.map.baidu.com/place/v2/search?query=银行&bounds=39.915,116.404,39.975,116.414&output=json&ak={您的密钥}

圆形区域检索参数

参数 是否必须 默认值 格式举例 含义
location 38.76623,116.43213

lat<纬度>,lng<经度>

周边检索中心点,不支持多个点
radius(r) 2000 周边检索半径,单位为米

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

http://api.map.baidu.com/place/v2/search?query=银行&location=39.915,116.404&radius=2000&output=xml&ak={您的密钥}

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 您的ak 用户的访问密钥,必填项。v2之前该属性为key。
sn 用户的权限签名。
timestamp 设置sn后该值必填。

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

服务示例:

http://api.map.baidu.com/place/v2/detail?uid=5a8fb739999a70a54207c130&output=json&scope=2&ak={您的密钥}

返回值:

{
    "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": "门店介绍:"
        }
    }
}

状态码附录

返回码 定义 英文返回描述
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”。