地理围栏 - 百度地图 API

简介

鹰眼的地理围栏服务，将根据轨迹判断终端是否进出围栏，并实时推送报警。鹰眼 Android SDK、iOS SDK 和 Web服务API 均提供地理围栏接口，详见：地理围栏

围栏的形状

目前鹰眼支持以下围栏形状：

**圆形围栏：**支持设置圆形围栏，一旦进出圆形范围则推送报警

**多边形围栏：**支持设置多边形围栏，一旦进出多边形围栏则推送报警

**线型围栏：**支持设置折线围栏，一旦偏离或回到设定路线则推送报警

**行政区围栏：**支持通过传入行政区名称，创建以行政区边界为界的围栏

客户端围栏和服务端围栏的说明

除围栏形状的区分，鹰眼Android SDK还提供客户端和服务端两种围栏：

**客户端围栏：**围栏的创建、计算和报警均在SDK完成，在 GPS 定位成功的情况下，无需联网即可完成围栏运算。可应用于手机终端网络不稳定情况下，仍需实时获取围栏报警的场景。例如，长途物流运输过程中，司机手机网络经常长时间断网或网络频繁切换，导致轨迹无法及时回传至服务端进行围栏运算，因此也无法获取实时报警。此时可同步创建客户端围栏，无需联网即可利用 GPS 轨迹点在手机本地进行围栏计算，APP 可及时收到报警信息进行相应的业务处理。

**服务端围栏：**围栏的创建、计算和报警的发起都在鹰眼服务端完成，依赖于轨迹点上传至服务端才能进行围栏进算。相较于客户端围栏，服务端围栏报警推送方式更多样：支持推送至 SDK，也支持推送至开发者的服务端，同时还支持报警信息批量查询

开发者可根据业务场景选择两类围栏中的一类，或两类同时使用。

围栏报警去噪的说明

无论是GPS定位还是网络定位都存在误差（也就是常说的定位漂移问题），噪点会造成围栏误报警。

目前鹰眼围栏进行了去噪处理，同时开放了 denoise 参数供开发者在创建围栏时设置，围栏运算时，一旦判断轨迹点定位精度大于denoise，则不参与围栏运算。比如设置denoise=30，则定位精度大于30米的轨迹点都不会参与围栏计算。

在此提供各定位模式的平均精度供开发者参考：GPS定位精度均值为10米，WIFI定位精度均值为24米，基站定位精度均值为210米。

围栏的应用场景

**1. 物流时效监控：**司机APP集成鹰眼SDK持续追踪轨迹。车辆管理人员通过服务端为每个司机创建出发地和目的地站点围栏，一旦监控对象进出围栏，鹰眼支持向鹰眼SDK 和开发者服务端推送报警信息。
**2. 路线偏离报警：**鹰眼v3.0新增路线围栏，可设定车辆行驶路线和偏离距离，一旦车辆偏离超过设定的距离，鹰眼围栏将推送报警。
**3. 用车行业运营区域监控：**利用鹰眼多边形地理围栏和行政区围栏功能，设置运营区域围栏，一旦判断车辆进/出运营区触发报警。

创建客户端围栏

目前客户端围栏仅支持圆形围栏，以圆形围栏为例介绍客户端围栏的创建

// 请求标识
int tag = 3;
// 轨迹服务ID
long serviceId = 0;
// 围栏名称
String fenceName = "local_circle";
// 监控对象
String monitoredPerson = "myTrace";
// 围栏圆心
com.baidu.trace.model.LatLng center = new com.baidu.trace.model.LatLng(39.9151190000, 116.4039630000);
// 围栏半径（单位 : 米）
double radius = 2000;
// 去噪精度
int denoise = 200;
// 坐标类型
CoordType coordType = CoordType.bd09ll;


// 创建本地圆形围栏请求实例
CreateFenceRequest localCircleFenceRequest = CreateFenceRequest.buildLocalCircleRequest(tag, serviceId,fenceName, monitoredPerson, center, radius, denoise, coordType);


// 初始化围栏监听器
OnFenceListener mFenceListener = new OnFenceListener() {
// 创建围栏回调
@Override
public void onCreateFenceCallback(CreateFenceResponse response) {}
// 更新围栏回调
@Override
public void onUpdateFenceCallback(UpdateFenceResponse response) {}
// 删除围栏回调
@Override
public void onDeleteFenceCallback(DeleteFenceResponse response) {}
// 围栏列表回调
@Override
public void onFenceListCallback(FenceListResponse response) {}
// 监控状态回调
@Override
public void onMonitoredStatusCallback(MonitoredStatusResponse 
response) {}
// 指定位置监控状态回调
@Override
public void onMonitoredStatusByLocationCallback(MonitoredStatusByLocationResponse response) {}
// 历史报警回调
@Override
public void onHistoryAlarmCallback(HistoryAlarmResponse response) {}
};


// 创建本地圆形围栏
mTraceClient.createFence(localCircleFenceRequest, mFenceListener);

创建服务端围栏

以创建多边形围栏为例，圆形和线型围栏与之类似，不再重复说明：

// 请求标识
int tag = 11;
// 轨迹服务ID
long serviceId = 0;
// 围栏名称
String fenceName = "server_polygon_fence";
// 监控对象
String monitoredPerson = "myTrace";
// 多边形顶点集
List<com.baidu.trace.model.LatLng> vertexes = new ArrayList<com.baidu.trace.model.LatLng>();
vertexes.add(new LatLng(40.0581750000, 116.3067370000));
vertexes.add(new LatLng(40.0583410000, 116.3079580000));
vertexes.add(new LatLng(40.0554970000, 116.3093600000));
vertexes.add(new LatLng(40.0554140000, 116.3078150000));
// 去噪精度
int denoise = 100;
// 坐标类型
CoordType coordType = CoordType.bd09ll;

// 创建服务端多边形围栏请求实例
CreateFenceRequest request = CreateFenceRequest.buildServerPolygonRequest(tag,
        serviceId, fenceName, monitoredPerson, vertexes, denoise, coordType);

// 初始化围栏监听器
OnFenceListener mFenceListener = new OnFenceListener() {
    //参见客户端围栏
};


// 创建服务端多边形围栏
mTraceClient.createFence(request, mFenceListener);

创建行政区围栏示例：

// 请求标识
int tag = 13;
// 轨迹服务ID
long serviceId = 0;
// 围栏名称
String fenceName = "server_district_fence";
// 监控对象
String monitoredPerson = "myTrace";

// 行政区划关键字
String keyword = "湖南省长沙市";
// 去噪精度
int denoise = 100;

// 创建服务端行政区划围栏请求实例
CreateFenceRequest request = CreateFenceRequest.buildServerDistrictRequest(tag,
        serviceId, fenceName, monitoredPerson, keyword, denoise);

// 初始化围栏监听器
OnFenceListener mFenceListener = new OnFenceListener() {
     //参见创建客户端围栏
}


// 创建服务端行政区划围栏
mTraceClient.createFence(request, mFenceListener);

围栏报警推送

围栏报警支持推送至鹰眼SDK，统一由OnTraceListener监听器中的onPushCallback()推送回调接口接收。开发者可在报警回调中触发自身业务，如发送短信至其他监控者、推送至开发者服务端等。

当接收报警的手机断网或网络状态不好时，会导致报警推送失败，鹰眼服务端将在后续的10分钟之内每隔15s推送一次，直至收到成功响应。若10分钟之后仍未成功，将不再推送，但报警记录将存储在鹰眼服务端。为避免因此造成报警漏接收，开发者可定期使用历史报警查询接口同步报警信息。

查询历史报警

不论围栏是否被删除，鹰眼将保留7天内的所有围栏报警信息，可通过queryFenceHistoryAlarmInfo方法并指定fenceId即可查询。

如：查询fenceId 等于100、101、102的三个围栏在30分钟内的报警信息：

// 请求标识
int tag = 8;
// 轨迹服务ID
long serviceId = 0;
// 开始时间
long startTime = System.currentTimeMillis() / 1000 - 30 * 60;
// 结束时间
long endTime = System.currentTimeMillis() / 1000;
// 监控对象
String monitoredPerson = "myTrace";
// 坐标类型
CoordType coordTypeOutput = CoordType.bd09ll;
// 围栏编号列表
List<Long> fenceIds = new ArrayList<Long>();
fenceIds.add(100L);
fenceIds.add(101L);
fenceIds.add(102L);

// 创建服务端围栏历史报警请求
HistoryAlarmRequest request = HistoryAlarmRequest.buildServerRequest(tag, serviceId, startTime, endTime,monitoredPerson, fenceIds, coordTypeOutput);

// 初始化围栏监听器
OnFenceListener mFenceListener = new OnFenceListener() {
     //参见创建客户端围栏
}

// 查询围栏历史报警信息
mTraceClient.queryFenceHistoryAlarmInfo(request, mFenceListener);

查询监控者状态

可通过queryMonitoredStatus()方法可以查询被监控者是在围栏内或围栏外（以被监控者上传至服务端的最新轨迹点计算）。

如：查询entityName="myTrace"所有围栏的状态：

// 请求标识
int tag = 9;
// 轨迹服务ID
long serviceId = 0;
// 监控对象
String monitoredPerson = "myTrace";
// 围栏编号列表，传 null，则表示查询该 entity 所有围栏。若填写fenceId 列表，则查询指定围栏的状态
List<Long> fenceIds = null;


// 创建查询服务端围栏监控状态请求
MonitoredStatusRequest request = MonitoredStatusRequest.buildServerRequest(tag,
        serviceId, monitoredPerson, fenceIds);


// 初始化围栏监听器
OnFenceListener mFenceListener = new OnFenceListener() {
    //参见客户端围栏
}

// 查询围栏监控者状态
mTraceClient.queryMonitoredStatus(request, mFenceListener);

根据坐标查询监控者状态

当轨迹点尚未上传时，无法通过queryMonitoredStatus()方法查询到准确的状态。此时，可通过queryMonitoredStatusByLocation()方法，传入一个被追踪者当前的坐标，判断被追踪者是在围栏内还是围栏外。

如：查询监控对象car1（指定位置：119.33,40.39，坐标类型为：百度经纬度）是在编号为1的围栏内还是外。

// 请求标识
int tag = 10;
// 轨迹服务ID
long serviceId = 0;
// 监控对象
String monitoredPerson = "myTrace";
// 围栏编号列表
List<Long> fenceIds = null;
// 位置坐标
com.baidu.trace.model.LatLng location = new com.baidu.trace.model.LatLng(40.0552720000, 116.307655000);
// 坐标类型
CoordType coordType = CoordType.bd09ll;


// 创建查询服务端围栏指定位置上监控状态请求实例
MonitoredStatusByLocationRequest request = MonitoredStatusByLocationRequest.buildServerRequest(tag,serviceId, monitoredPerson, fenceIds, location, coordType);


// 初始化围栏监听器
OnFenceListener mFenceListener = new OnFenceListener() {
    //参见客户端围栏
}