地理围栏报警

简介

围栏状态和报警信息查询类接口,包括以下5个接口:

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

注:鹰眼 v3.0使用全新域名http://yingyan.baidu.com/api/v3,请开发者注意。

坐标系说明

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


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


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


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


非中国地区地图,统一使用WGS84坐标


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

querystatus——查询监控对象在围栏内或外

接口说明

查询监控对象在围栏内或外

请求URI

http://yingyan.baidu.com/api/v3/fence/querystatus

HTTP请求方式

GET

请求参数

参数名 参数含义 类型 是否必填 备注
ak 用户的ak string
service_id service的ID,service 的唯一标识。 int
在轨迹管理台创建鹰眼服务时,系统返回的 service_id


monitored_person 监控对象的 entity_name string(128)


tactis 查询围栏状态 string

可支持的关键字:

1、in

2、out

Tactis和fence_ids 两个字段不兼容。

二者都不填,则查询监控对象上的所有围栏状态

fence_ids 围栏实体的id列表 “int,int…”

Tactis和fence_ids 两个字段不兼容 二者都不填,则查询监控对象上的所有围栏状态

返回参数

参数名 参数含义 类型 备注
status 状态码 int 返回状态,0为成功
message 响应信息 string 对status的中文描述
size 返回结果的数量 int
monitored_statuses 报警的数量 array
fence_id 围栏 id int
monitored_status 状态 string unknown:未知状态

in:在围栏内

out:在围栏外

请求示例

http://yingyan.baidu.com/api/v3/fence/querystatus?service_id=100000&monitored_person=小明&fence_ids=1,2,3&ak=开发者的ak

返回示例

JSON
{
 "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天之内的报警信息。

请求URI

http://yingyan.baidu.com/api/v3/fence/historyalarm

HTTP请求方式

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 坐标

返回参数

参数名 参数含义 类型 备注
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。

请求示例

http://yingyan.baidu.com/api/v3/fence/historyalarm?service_id=127980&monitored_person=小明&fence_ids=1&start_time=1489420800&end_time=1489507200&ak=开发者的ak

返回示例

JSON
{
   "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的围栏报警信息

接口说明

批量同步某时间段内 service 所有围栏的报警信息。

注:即使围栏或监控对象已被删除,仍能同步7天之内这些围栏的报警信息。

请求URI

http://yingyan.baidu.com/api/v3/fence/batchhistoryalarm

HTTP请求方式

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_index与page_size一起计算从第几条结果返回,代表返回第几页。
page_size 分页大小 int(1-1000) 可选 默认值为500。page_size与page_index一起计算从第几条结果返回,代表返回结果中每页有几条记录。

返回参数

参数名 参数含义 类型 备注
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。

请求示例

http://yingyan.baidu.com/api/v3/fence/batchhistoryalarm?&service_id=127980&start_time=1489420800&end_time=1489424400&ak=开发者的ak

返回示例

JSON
{
   "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请求,在请求中推送围栏报警信息。

yingyan_guide_webmanager_alert.png

使用须知

1. 鹰眼服务端将向开发者发送两类请求

【地址校验请求】百度鹰眼在拿到开发者的URL的时候,需要对该URL做有效性校验,保证URL的可用性;

【报警信息推送请求】百度鹰眼地址校验通过后,将通过该类请求向开发者推送围栏报警信息。

配置地址完成后,鹰眼服务端将向开发者服务端发送地址校验请求,如成功后,将不再发送校验类请求,直到变更配置地址。

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

3. 开发者接收报警信息后的响应信息请务必按照格式填写,且为JSON格式,服务方可正确设置成功。具体格式请参考本页面最下方示例。


给开发者的建议:开发者在接收到该类消息之后,使用异步方式做业务处理。即获取到消息内容之后,立即返回,而报警推送的业务处理则在另外的线程中处理。

开发者使用服务步骤

第一步:开发者搭建服务,使用http协议,构建服务端接收报警信息的URL

请注意,该URL请求无需参数,URL中不可含有& ?等特殊字符)

开发者接收报警信息的服务要求必须及时对鹰眼服务端发送的请求做出响应,如鹰眼服务端1s之内没有收到响应信息,则报警失败。

假设用户提供的URL为http://your.server.name:port/your/path

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

配置成功后,鹰眼服务端立即向开发者发送校验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 请求值:baidu_yingyan

请求来源标记。

string 用户可以通过获取这个标志来判断一个http请求是否来自百度鹰眼。
Content-Encoding 请求值:gzip

消息压缩标记。

string 为减少请求量,提高网络传输速度,鹰眼会对请求内容做gzip压缩,此时请求头中将包含该字段,用户在接收到该类请求时,需要对请求体中内容做gzip解压缩,解压之后的内容即为报警推送消息。
Content-Type 请求值:application/json string 请求为JSON格式。

当Content-Encoding为gzip标记时,请求body为压缩之后的字节流,解压之后为JSON格式。

请求体参数

参数名 参数含义 类型 备注
type 消息类型 int 取值1或者2

1:当type=1时,校验该URL为有效URL。此时,content为空或不存在。开发者无需对消息内容做任何处理,只需正常返回即可。

2:当type=2时,推送报警信息,开发者可取content中的内容做其他业务处理。

service_id service的唯一标识,当前报警信息所属的鹰眼服务ID int 在轨迹管理台创建鹰眼服务时,系统返回的 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发送推送数据。
Content-Type 返回值:application/json string 返回JSON格式。

返回体参数

参数名 参数含义 类型 是否必须 备注
status 返回状态码 int 0标识成功,非0标识失败。
message 返回信息 string 对status的中文描述。

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

请求示例

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

完整请求示例
请求头
   "SignId": "baidu_yingyan"
   "Content-Type": "application/json"
请求体
 {
     "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"
   "Content-Type": "application/json"
返回体
 {
     "status":0,
     "message":"成功"
 }