浏览器版本低!无法浏览完整内容,建议升级或更换浏览器。
简介

地理围栏报警类接口主要提供
1. 查询监控对象在围栏内/外:查询被监控对象在指定围栏内或外,也支持查询被监控对象目前相对于所有围栏的状态
2. 查询围栏报警信息:支持查询某时间段内单个围栏或该 service 下所有围栏的报警信息
3. 服务端报警信息推送:鹰眼将报警信息实时推送至开发者的服务端

接口列表
模块接口名称功能说明
fencequerystatus 查询监控对象在围栏内或外
querystatusbylocation查询坐标在围栏内或外
historyalarm查询某监控对象的历史报警信息
batchhistoryalarm批量查询某 service 下时间段以内的所有报警信息,用于服务端报警同步
服务端报警推送查询某监控对象的历史报警信息
坐标系说明

目前中国主要有以下三种坐标系:

WGS84:为一种大地坐标系,也是目前广泛使用的GPS全球卫星定位系统使用的坐标系
GCJ02:是由中国国家测绘局制订的地理信息系统的坐标系统。由WGS84坐标系经加密后的坐标系
BD09:为百度坐标系,在GCJ02坐标系基础上再次加密。其中bd09ll表示百度经纬度坐标,bd09mc表示百度墨卡托米制坐标
非中国地区地图,统一使用WGS84坐标

鹰眼 Web服务API v3.0的默认输入输出参数为百度坐标(BD09),同时可通过"coord_type","coord_type_input","coord_type_output"(以各服务参数介绍为准)控制输入输出的坐标类型,鹰眼将自动完成转换。

围栏报警接口使用小贴士

1. 为保证轨迹点的顺序性,使用查询围栏报警信息(querystatus)接口时,轨迹点上传成功后,服务端会有15秒左右报警延迟。
2. 围栏报警是通过计算监控对象的轨迹来进行状态判断。为提高报警准确性,服务端将针对轨迹做去噪纠偏。
3. 若监控对象的轨迹点异常,围栏报警计算时将会过滤该点,建议使用实际路测数据测试地理围栏报警服务功能。

在使用围栏时,发现轨迹点未触发围栏报警,开发者可从以下几方面排查原因:
1. 轨迹点的定位时间是否早于围栏创建时间,若如此,此点将不参与围栏计算;
2. 轨迹点被认为是噪点被去除,从而不参与围栏计算。噪点的判定方法,一方面是轨迹点定位误差是否超过了开发者创建围栏时设置的去噪阈值(denoise),一方面是鹰眼内部的去噪策略,开发者可通过轨迹管理台对比原始轨迹和去噪后轨迹来辨别噪点;
3. 轨迹点不是真实轨迹,而是开发者构造的虚拟轨迹,围栏在计算时也将忽略这部分轨迹;
4. 轨迹点上传顺序错乱问题,若定位时间较新的轨迹点已上传并参与围栏计算了,那么此时再上传定位时间较旧的轨迹点,则旧轨迹点不再参与围栏计算。

接口说明
querystatus——查询监控对象相对围栏的状态

查询被监控对象在指定围栏内或外,也支持查询被监控对象目前相对于所有围栏的状态

请求URL

https://yingyan.baidu.com/api/v3/fence/querystatus
//GET请求

请求参数
参数名称字段含义数据类型是否必填备注
ak

用户的AK

string
service_id

service的ID,service 的唯一标识

intservice 的唯一标识。在轨迹管理台创建鹰眼服务时,系统返回的 service_id
monitored_person

监控对象的 entity_name

string(128)
fence_ids

围栏实体的id列表

“int,int…”

若填写,则按照指定的id全部返回围栏状态,此时page_index和page_size不生效。
若不填,则查询监控对象上的所有围栏状态。
fence_ids中最多填写1000个id。

page_index

分页索引

int(1到2^21-1)默认值:1,与page_size一起计算从第几条结果返回,代表返回第几页
page_size

每页返回数据量

int(1-5000)

默认值:1000
返回结果最大个数与page_index一起计算从第几条结果返回,代表返回结果中每页有几个轨迹点

sn

用户的权限签名,若用户所用AK的校验方式为SN校验时该参数必须。SN计算方法

string
返回参数
参数名字段含义类型备注
status状态码int返回状态,0为成功
message响应信息string对status的中文描述
total总的查询结果数量int
size本页返回的结果数量int
monitored_statuses报警的数量array
fence_id围栏 idint
monitored_status状态stringunknown:未知状态
in:在围栏内
out:在围栏外
请求示例
https://yingyan.baidu.com/api/v3/fence/querystatus?service_id=100000&monitored_person=小明&fence_ids=1,2,3&ak=<用户的'''AK>'''
返回示例
{
"status": 0,
"message": "成功",
"size": 2,
"monitored_statuses": [
{
"fence_id": 2,
"monitored_status": "in"
},
{
"fence_id": 3,
"monitored_status": "unknown"
}
]
}
querystatusbylocation——根据坐标查询监控对象相对围栏的状态

简介:传入坐标,计算该坐标在围栏内/外。
适用场景:由于querystatus接口需要保证到轨迹点的顺序性,因此查询状态会有15s的延迟。若开发者对即时性要求甚高,如共享汽车、共享单车落锁时对于是否停在规定围栏内的判断,可使用querystatusbylocation接口:传入当下定位的坐标,则鹰眼将计算该坐标相对于围栏的状态(内/外)。

请求URL

https://yingyan.baidu.com/api/v3/fence/querystatusbylocation
//GET请求

请求参数
参数名称字段含义数据类型是否必填备注
ak

用户的AK

string
service_id

service的ID,service 的唯一标识

int在轨迹管理台创建鹰眼服务时,系统返回的 service_id
monitored_person

监控对象的 entity_name

string(128)
fence_ids

围栏实体的id列表

“int,int…”

若填写,则按照指定的id全部返回围栏状态,此时page_index和page_size不生效。
若不填,则查询监控对象上的所有围栏状态。
fence_ids中最多填写1000个id。

longitude

经度

double指定监控对象所在坐标的经度
latitude

纬度

double指定监控对象所在坐标的纬度
coord_type

坐标类型

string

坐标类型定义如下:
wgs84:卫星定位经纬度 gcj02:国测局经纬度 bd09ll:百度经纬度

page_index

分页索引

int(1到2^21-1)默认值:1,与page_size一起计算从第几条结果返回,代表返回第几页
page_size

每页返回数据量

int(1-5000)

默认值:1000
返回结果最大个数与page_index一起计算从第几条结果返回,代表返回结果中每页有几个轨迹点

sn

用户的权限签名,若用户所用AK的校验方式为SN校验时该参数必须。SN计算方法

string
返回参数
参数名字段含义类型备注
status状态码int返回状态,0为成功
message响应信息string对status的中文描述
total总的查询结果数量int
size本页返回的结果数量int
monitored_statuses报警的数量array
fence_id围栏 idint
monitored_status状态stringunknown:未知状态
in:在围栏内
out:在围栏外
请求示例
https://yingyan.baidu.com/api/v3/fence/querystatusbylocation?service_id=100000&monitored_person=小明&fence_ids=1,2,3&longitude=116.334129&latitude=40.010939&coord_type=bd09ll&ak=<用户的'''AK>'''
返回示例
{
"status": 0,
"message": "成功",
"size": 2,
"monitored_statuses": [
{
"fence_id": 2,
"monitored_status": "in"
},
{
"fence_id": 3,
"monitored_status": "unknown"
}
]
}
historyalarm——查询某监控对象的围栏报警信息

查询围栏的监控对象7天以内(包含7天)的围栏报警信息,7天以外的报警信息将被删除。
注:即使围栏或监控对象已被删除,仍能根据 fence_id 和 monitored_person 查询7天之内的报警信息。

请求URL

https://yingyan.baidu.com/api/v3/fence/historyalarm
//GET请求

请求参数
参数名称字段含义数据类型是否必填备注
ak

用户的AK

string
service_id

service的ID,service 的唯一标识

int在轨迹管理台创建鹰眼服务时,系统返回的 service_id
monitored_person

监控对象的 entity_name

string(128)
fence_ids

围栏实体的id列表

“int,int…”

若不填,则查询监控对象所有围栏的报警信息

start_time

开始时间

UNIX 时间戳若不填,则返回7天内所有报警信息
end_time

结束时间

UNIX 时间戳若不填,则返回7天内所有报警信息
coord_type_output

返回坐标类型

string

默认为 bd09ll。
用于控制返回结果的坐标类型
可选值如下:
bd09ll:百度经纬度
gcj02:国测局经纬度
注:国外均返回 wgs84 坐标

sn

用户的权限签名,若用户所用AK的校验方式为SN校验时该参数必须。SN计算方法

string
返回参数
参数名字段含义类型备注
status状态码int返回状态,0为成功
message响应信息string对status的中文描述
size返回的结果数量int
alarms报警的数量array
fence_id围栏 id,唯一标识符int
fence_name围栏的名称string
monitored_person监控对象string
action触发动作string可能的返回值:
enter:进入围栏
exit:离开围栏
alarm_point触发围栏报警轨迹点
longitude监控对象触发围栏时的经度double
latitude监控对象触发围栏时的纬度double
radius定位精度int单位:米
coord_type返回的坐标类型string仅在国外区域返回该字段,返回值为:wgs84
loc_time围栏实际触发时间,即触发围栏报警的轨迹点的定位时间UNIX 时间戳即使触发围栏的轨迹点未实时上传,由于轨迹点中携带了 loc_time,鹰眼仍能根据 loc_time判断围栏实际触发时间。
create_time服务端接收到报警信息的时间UNIX 时间戳由于鹰眼 API 围栏为服务端围栏,即只有当轨迹点上传鹰眼服务端时,才能进行围栏触发判断。因此服务端接收到报警的时间可能由于轨迹点上传的不及时性,而晚于围栏实际触发时间 loc_time。例如,轨迹点实际触发围栏时间为13:00,但若由于各种原因,轨迹点上传至服务端进行围栏计算的时间为14:00,则该报警的 create_time为14:00。
pre_point触发围栏报警轨迹点的上一个轨迹点
longitude监控对象触发围栏时的经度double
latitude监控对象触发围栏时的纬度double
radius定位精度int单位:米
coord_type返回的坐标类型string仅在国外区域返回该字段,返回值为:wgs84
loc_time围栏实际触发时间,即触发围栏报警的轨迹点的定位时间UNIX 时间戳即使触发围栏的轨迹点未实时上传,由于轨迹点中携带了 loc_time,鹰眼仍能根据 loc_time判断围栏实际触发时间。
create_time服务端接收到报警信息的时间UNIX 时间戳由于鹰眼 API 围栏为服务端围栏,即只有当轨迹点上传鹰眼服务端时,才能进行围栏触发判断。因此服务端接收到报警的时间可能由于轨迹点上传的不及时性,而晚于围栏实际触发时间 loc_time。例如,轨迹点实际触发围栏时间为13:00,但若由于各种原因,轨迹点上传至服务端进行围栏计算的时间为14:00,则该报警的 create_time为14:00。
请求示例
https://yingyan.baidu.com/api/v3/fence/historyalarm?service_id=127980&monitored_person=小明&fence_ids=1&start_time=1489420800&end_time=1489507200&ak=<用户的AK>
返回示例
{
"status": 0,
"size": 1,
"message": "成功",
"alarms": [
{
"fence_id": 1,
"fence_name":"围栏名称",
"monitored_person":"entity1",
"action": "exit",
"alarm_point":{
"longitude":116.2333,
"latitude":43.892,
"radius":27,
"loc_time": 1419388604
"create_time": 1419388609
},
"pre_point":{
"longitude":116.2367,
"latitude":43.894,
"radius":28,
"loc_time": 1419388724
"create_time": 1419388729
}
}
]
}
batchhistoryalarm——批量查询所有围栏报警信息

批量查询某 service 7天内任意1小时,所有围栏的报警信息。

请求URL

https://yingyan.baidu.com/api/v3/fence/batchhistoryalarm
//GET请求

请求参数
参数名称字段含义数据类型是否必填备注
ak

用户的AK

string
service_id

service的ID,service 的唯一标识

int在轨迹管理台创建鹰眼服务时,系统返回的 service_id
start_time

开始时间

UNIX 时间戳查询的时间是服务端接收到报警的时间,即报警信息的 create_time。例如,轨迹点实际触发围栏时间为13:00,但若由于各种原因,轨迹点上传至服务端进行围栏计算的时间为14:00,则该报警的 create_time为14:00。
end_time

结束时间

UNIX 时间戳结束时间需大于开始时间,但不可超过1小时。即每次请求,最多只能同步1个小时时长的报警信息。
coord_type_output

返回坐标类型

string

默认为 bd09ll。
用于控制返回结果的坐标类型
可选值如下:
bd09ll:百度经纬度
gcj02:国测局经纬度
注:国外均返回 wgs84 坐标

page_index

分页索引

int(1到2^32-1)默认值:1,与page_size一起计算从第几条结果返回,代表返回第几页
page_size

每页返回数据量

int(1-1000)

默认值为500。page_size与page_index一起计算从第几条结果返回,代表返回结果中每页有几条记录。

sn

用户的权限签名,若用户所用AK的校验方式为SN校验时该参数必须。SN计算方法

string
返回参数
参数名字段含义类型备注
status状态码int返回状态,0为成功
message响应信息string对status的中文描述
total符合条件的总报警数int
size本页返回的结果条数int
alarms报警的数量array
fence_id围栏 id,唯一标识符int
fence_name围栏的名称string
monitored_person监控对象string
action触发动作string可能的返回值:
enter:进入围栏
exit:离开围栏
alarm_point触发围栏报警轨迹点
longitude监控对象触发围栏时的经度double
latitude监控对象触发围栏时的纬度double
radius定位精度int单位:米
coord_type返回的坐标类型string仅在国外区域返回该字段,返回值为:wgs84
loc_time围栏实际触发时间,即触发围栏报警的轨迹点的定位时间UNIX 时间戳即使触发围栏的轨迹点未实时上传,由于轨迹点中携带了 loc_time,鹰眼仍能根据 loc_time判断围栏实际触发时间。
create_time服务端接收到报警信息的时间UNIX 时间戳由于鹰眼 API 围栏为服务端围栏,即只有当轨迹点上传鹰眼服务端时,才能进行围栏触发判断。因此服务端接收到报警的时间可能由于轨迹点上传的不及时性,而晚于围栏实际触发时间 loc_time。例如,轨迹点实际触发围栏时间为13:00,但若由于各种原因,轨迹点上传至服务端进行围栏计算的时间为14:00,则该报警的 create_time为14:00。
pre_point触发围栏报警轨迹点的上一个轨迹点
longitude监控对象触发围栏时的经度double
latitude监控对象触发围栏时的纬度double
radius定位精度int单位:米
coord_type返回的坐标类型string仅在国外区域返回该字段,返回值为:wgs84
loc_time围栏实际触发时间,即触发围栏报警的轨迹点的定位时间UNIX 时间戳即使触发围栏的轨迹点未实时上传,由于轨迹点中携带了 loc_time,鹰眼仍能根据 loc_time判断围栏实际触发时间。
create_time服务端接收到报警信息的时间UNIX 时间戳由于鹰眼 API 围栏为服务端围栏,即只有当轨迹点上传鹰眼服务端时,才能进行围栏触发判断。因此服务端接收到报警的时间可能由于轨迹点上传的不及时性,而晚于围栏实际触发时间 loc_time。例如,轨迹点实际触发围栏时间为13:00,但若由于各种原因,轨迹点上传至服务端进行围栏计算的时间为14:00,则该报警的 create_time为14:00。
请求示例
https://yingyan.baidu.com/api/v3/fence/batchhistoryalarm?&service_id=127980&start_time=1489420800&end_time=1489424400&ak=<用户的AK>
返回示例
{
"status": 0,
"total": 2000,
"size": 500,
"message": "成功",
"alarms": [
{
"fence_id": 1,
"fence_name":"学校",
"monitored_person":"小明",
"action": "exit",
"alarm_point":{
"longitude":116.2333,
"latitude":43.892,
"radius":27,
"loc_time": 1419388604
"create_time": 1419388609
},
"pre_point":{
"longitude":116.2367,
"latitude":43.894,
"radius":28,
"loc_time": 1419388724
"create_time": 1419388729
}
},
{
"fence_id": 1,
"fence_name":" 学校",
"monitored_person":"小明",
"action": "enter",
"alarm_point":{
"longitude":116.2333,
"latitude":43.892,
"radius":12,
"loc_time": 1419387405,
"create_time": 1419387405
},
"pre_point": {
"longitude":116.2367,
"latitude":43.894,
"radius":15,
"loc_time": 1419387465,
"create_time": 1419387465
}
}
]
}
服务端围栏报警信息推送

鹰眼服务端支持将报警推送至开发者的服务端、鹰眼SDK(了解报警推送至鹰眼SDK功能请前往Android鹰眼SDKiOS鹰眼SDK)。

若开发者要将围栏报警信息推送至开发者的服务端,需要开发者在自己的服务端实现自己的接收报警信息的HTTP服务,同时在轨迹管理台设置页面同步配置服务地址;百度鹰眼将通过该地址向开发者的服务端发送http请求,在请求中推送围栏报警信息。

使用须知

1,鹰眼服务端将向开发者发送两类请求:
【地址校验请求】百度鹰眼在拿到开发者的URL的时候,需要对该URL做有效性校验,保证URL的可用性
【报警信息推送请求】百度鹰眼地址校验通过后,将通过该类请求向开发者推送围栏报警信息

2,鹰眼服务端推送报警时,开发者返回信息接收是否成功。如果1s之内没有收到响应信息,则推送报警失败。若推送失败,将在后续的10分钟之内每隔60s推送一次,直至收到成功响应。若10分钟之后仍未成功,将不再推送,但报警记录将存储在鹰眼服务端。为避免因此造成报警漏接收,开发者可定期使用历史报警查询接口同步报警信息

3,开发者接收报警信息后的响应信息请务必按照格式填写,且为JSON格式,服务方可正确设置成功。具体格式请参考本页面最下方示例。
给开发者的建议:开发者在接收到该类消息之后,使用异步方式做业务处理。即获取到消息内容之后,立即返回,而报警推送的业务处理则在另外的线程中处理。

开发者使用服务步骤

第一步:开发者搭建服务,使用http协议,构建服务端接收报警信息的URL
(请注意,该URL请求无需参数,URL中不可含有& ?等特殊字符)
客户服务端需要支持 Content-Type: application/json Content-Type: application/x-www-form-urlencoded
开发者接收报警信息的服务要求必须及时对鹰眼服务端发送的请求做出响应,如鹰眼服务端1s之内没有收到响应信息,则报警失败。
假设用户提供的URL为http://your.server.name:port/your/path

第二步:在轨迹管理台设置页面配置该URL

配置成功后,鹰眼服务端立即向开发者发送校验URL请求:
1.校验请求:POST请求,仅配置地址完成后首次报警前发送该请求。
POST内容为JSON格式消息,{“type”:1, ”service_id”:2741}
校验成功后,当鹰眼服务端围栏触发报警时,将向此URL推送地理围栏报警信息。
2.报警推送请求:POST请求,围栏触发报警即发送该类请求
POST内容为JSON格式消息,{“type”:2, ”service_id”:2741, ”content”:[报警信息数组]}

接口说明
支持将鹰眼服务端地理围栏报警信息推送至开发者的服务端。

请求URI
开发者构建围栏报警请求URL,鹰眼将根据此URL向开发者服务端发送请求。
该URL需要同步在轨迹管理台配置页面配置,使鹰眼能够唯一识别对应service_id与开发者服务端地址。

HTTP请求方式
POST

数据格式
请求和返回均为JSON格式

公共请求头
参数名称字段含义数据类型备注
SignId

请求来源标记

string

允许的请求值:baidu_yingyan
用户可以通过获取这个标志来判断一个http请求是否来自百度鹰眼。

Content-Encoding

消息压缩标记

string

允许的请求值:gzip 或 空值
为减少请求量,提高网络传输速度,鹰眼可对请求内容做gzip压缩,此时请求头中将包含该字段。
用户在接收到该类型请求时,需要判断Content-Encoding是否为gzip压缩:如果Content-Encoding=gzip,需要对请求体进行解压缩,解压缩之后的内容即为报警推送消息;如果Content-Encoding为空,则无需进行解压缩。

请求体参数
参数名字段含义类型备注
type消息类型int取值1或者2
1:当type=1时,校验该URL为有效URL。此时,content为空或不存在。开发者无需对消息内容做任何处理,只需正常返回即可。
2:当type=2时,推送报警信息,开发者可取content中的内容做其他业务处理。
service_idservice的唯一标识,当前报警信息所属的鹰眼服务IDint在轨迹管理台创建鹰眼服务时,系统返回的 service_id
content报警信息数组array当type为1时,content为空或不存在。
该字段为数组格式,数组的每个内容都是一个推送信息。
fence_id围栏 id,唯一标识符int一条推送返回一个报警信息
fence_name围栏的名称string
monitored_person监控对象string监控对象的entity_name
action触发动作string可能的返回值:
enter:进入围栏
exit:离开围栏
alarm_point触发围栏报警轨迹点
longitude监控对象触发围栏时的经度double
latitude监控对象触发围栏时的纬度double
radius定位精度int单位:米
coord_type返回的坐标类型string国内为百度坐标系:bd09ll;国外均为 wgs84坐标系:wgs84
loc_time围栏实际触发时间,即触发围栏报警的轨迹点的定位时间UNIX 时间戳即使触发围栏的轨迹点未实时上传,由于轨迹点中携带了 loc_time,鹰眼仍能根据 loc_time判断围栏实际触发时间。
create_time服务端接收到报警信息的时间UNIX 时间戳由于鹰眼 API 围栏为服务端围栏,即只有当轨迹点上传鹰眼服务端时,才能进行围栏触发判断。因此服务端接收到报警的时间可能由于轨迹点上传的不及时性,而晚于围栏实际触发时间 loc_time。例如,轨迹点实际触发围栏时间为13:00,但若由于各种原因,轨迹点上传至服务端进行围栏计算的时间为14:00,则该报警的 create_time为14:00。
pre_point触发围栏报警轨迹点的上一个轨迹点
longitude监控对象触发围栏时的经度double
latitude监控对象触发围栏时的纬度double
radius定位精度int单位:米
coord_type返回的坐标类型string国内为百度坐标系:bd09ll;国外均为wgs84坐标系:wgs84
loc_time围栏实际触发时间,即触发围栏报警的轨迹点的定位时间UNIX 时间戳即使触发围栏的轨迹点未实时上传,由于轨迹点中携带了 loc_time,鹰眼仍能根据 loc_time判断围栏实际触发时间。
create_time服务端接收到报警信息的时间UNIX 时间戳由于鹰眼 API 围栏为服务端围栏,即只有当轨迹点上传鹰眼服务端时,才能进行围栏触发判断。因此服务端接收到报警的时间可能由于轨迹点上传的不及时性,而晚于围栏实际触发时间 loc_time。例如,轨迹点实际触发围栏时间为13:00,但若由于各种原因,轨迹点上传至服务端进行围栏计算的时间为14:00,则该报警的 create_time为14:00。
公共返回头
参数名称字段含义数据类型备注
SignId

返回值:baidu_yingyan
请求来源标记。

string

根据该字段识别响应身份,若未返回该字段,则视为URL校验失败,不再对该URL发送推送数据。

返回体参数
参数名称字段含义数据类型备注
status

返回状态码

int

0或非0值

message

返回信息

string

对status的中文描述。

百度鹰眼不对响应内容做处理,只要http的状态码为200,则视为发送成功(返回非200的其他任何内容都视为该次调用失败)。此响应内容中的status不作为成功与否的标志,也不会根据此status的值做重试处理。

请求示例

以下是一个校验消息的完整请求示例:

请求头

"SignId": "baidu_yingyan"

请求体

{
"type":1,
"service_id":2741
}

以下是一个推送消息的完整请求示例:

请求头

"
SignId": "baidu_yingyan"
"Content-Encoding": "gzip"

请求体(解压缩之后)

{
"type":2,
"service_id": 2741,
"content":[
{
"fence_id": 1,
"fence_name": "A_01",
"monitored_person": "A001",
"action": "enter",
"alarm_point": {
"longitude": 113.29251520916,
"latitude": 23.45610760748,
"radius": 3,
"coord_type" : "bd09ll",
"loc_time": 1490179579,
"create_time": 1490179593
},
"pre_point": {
"longitude": 113.20148113236,
"latitude": 23.431332045033,
"radius": 10,
"coord_type" : "bd09ll",
"loc_time": 1490179557,
"create_time": 1490179569
}
}
]
}
返回示例

返回头

"SignId": "baidu_yingyan"

返回体

{
"status":0,
"message":"成功"
}

上一篇

地理围栏管理

下一篇

批量导出轨迹

本篇文章对您是否有帮助?