产品介绍

地理围栏服务是一类HTTP接口，提供在服务端，增删改查地理围栏的功能，同时支持对于设备与围栏关系进行监控。

适用场景

地理围栏服务适用于需要针对特定区域，监控用户位置与区域关系的场景中。包括但不限于：签到打卡类场景，在用户打卡操作前，判断用户是否已经在对应的地理围栏区域内；

共享单车类场景，当用户骑车离开合法使用区域时，第一时间获知；或当用户关锁支付时，判断用户是否停在了合法区域内；

线下门店促销场景，当获取到用户定位在促销门店区域的附近时，向用户发送引导进入店铺的促销信息。

使用限制

目前开通web服务权限的开发者key都具有初级围栏使用权限(10个围栏)，详细配额请在配额说明页查询。

使用说明

第一步，申请”Web服务API”密钥(Key)，即可获得初级配额的围栏使用权限。

第二步，使用创建围栏接口新增围栏，目前支持圆形围栏和多边形围栏。使用其他增删改查接口管理围栏；

第三步，实际使用中，先获取用户设备位置，然后使用设备围栏监控接口，进行设备与围栏关系的判断。获取用户设备位置的方法，可参考定位相关信息。

需要注意的是：如无特殊声明，接口的输入参数和输出数据编码全部统一为UTF-8。

接口对应的请求方式：

方法名称请求方式

创建围栏POST

查询围栏GET

更新围栏PATCH

围栏启动&停止PATCH

删除围栏DELETE

围栏设备监控GET

创建围栏

创建地理围栏API服务POST请求地址：curl -i -X POST https://restapi.amap.com/v4/geofence/meta?key=用户key -d 'json'

请将json参数添加到body体中发送。query请求参数

key：用户唯一标识，必填。用户在高德地图官网申请Web服务API类型Keyjson请求参数

参数名含义规则说明是否必填缺省值

name围栏名称字母&数字&汉字必填无

center圆形围栏中心点longitude,latitude圆形围栏必填与points互斥无

radius圆形围栏半径单位：米。范围0~5000。圆形围栏必填与points互斥无

points多边形围栏坐标点lon1,lat1;lon2,lat2;lon3,lat3(3<=点个数<=5000)。多边形围栏外接圆半径最大为5000米。多边形围栏必填无

enable围栏监控状态布尔类型可选true

valid_time过期日期围栏有效截止日期，过期后不对此围栏进行维护(围栏数据过期删除)；

不能设定创建围栏时间点之前的日期；

格式yyyy-MM-dd； 请设置2055年之前的日期可选创建时间后90天；

repeat一周内围栏监控日期的重复模式星期缩写列表，用","或“;”隔开。

样例："Mon,Sat"

表示周一和周六有效。

星期简称如下(首字母大写)：

Mon,Tues,Wed,Thur,Fri,Sat,Sun

repeat和fixed_date不能同时缺省或同时为空，二者所指出的监控日期为“或”关系可选，repeat和fixed_date不能同时缺省或同时为空，二者所指出的监控日期为“或”关系无

fixed_date指定日期列表格式"date1;date2;date3"； date格式"yyyy-MM-dd"；

最大个数180，不能设定过去日期；

repeat和fixed_date不能同时缺省或同时为空，二者所指出的监控日期为“或”关系；可选，repeat和fixed_date不能同时缺省或同时为空，二者所指出的监控日期为“或”关系无

time一天内围栏监控时段开始时间和结束时间定义一时间段，可设置多个时间段，时间段按照时间顺序排列，各时间段不可重叠；

拼接字符串格式如："startTime1,endTime1;startTime2,endTime2"；

最大个数24；

不可为空；

范围00:00-23:59；

时间段不可重叠；

时间段长度>15min；可选默认为00:00,23:59；

desc围栏描述信息可选无

alert_condition配置触发围栏所需动作触发动作分号分割

enter;leave(进入、离开触发)可选无返回结果参数说明

名称含义

data返回数据内容消息体

gid围栏全局id是一个地理围栏实体的全局id(gid)，是围栏的唯一标识，可以用来查找该围栏实体本身的详细信息

id围栏id为预留字段，暂未使用，固定返回0。

message状态说明信息

status状态值

errcode错误码

errmsg错误描述信息服务示例

请求POST地址：https://restapi.amap.com/v4/geofence/meta?key=用户key

请求json参数：{"name": "测试围栏名称","center": "115.672126,38.817129","radius": "1000","enable": "true","valid_time": "2017-05-19",

"repeat": "Mon,Tues,Wed,Thur,Fri,Sat,Sun","time": "00:00,11:59;13:00,20:59","desc": "测试围栏描述","alert_condition": "enter;leave"}

返回结果：{"data": {"gid": "01c7b927-9f6f-4d4e-a0b0-7887dcefb3c4","id": "0","message": "成功","status": "0"},"errcode": 0,"errmsg": "OK"}

上述示例中，创建了一个圆形围栏。创建成功后，返回了该围栏的id。

查询围栏

该接口可支持多种方式的围栏查询，同时可以对返回消息的分页方式进行设定。只能查询已经创建，未被删除的围栏。

查询围栏API服务GET请求地址：curl -i -X GET https://restapi.amap.com/v4/geofence/meta?key=用户keyquery请求参数

参数名含义规则说明是否必填缺省值

key请求服务权限标识必填无

id围栏id数字可选无

gid围栏全局id数字&字母&-可选无

name围栏名称支持字母&数字&汉字，40个字符以内可选无

page_no当前页码数字可选1

page_size每页数量数字可选20

enable围栏激活状态布尔类型可选无

start_time按创建时间查询的起始时间yyyy-MM-dd HH:mm:ss可选无

end_time按创建时间查询的结束时间yyyy-MM-dd HH:mm:ss可选无返回结果参数说明

参数名含义

data返回内容消息体

page_no当前页码

page_size每页记录数

rs_list围栏列表

adcode围栏所在地区adcode

alert_condition围栏监控触发条件

center圆形围栏中心点

create_time围栏创建时间

enable围栏激活状态

fixed_date指定日期

gid围栏全局id

id围栏id

key开发者key

name围栏名称

points多边形围栏点

radius圆形围栏半径

repeat一周内围栏监控的重复星期

time一天内监控的具体时段

valid_time过期日期

total_record总记录数

errcode错误码

errmsg错误信息服务示例

请求GET地址：https://restapi.amap.com/v4/geofence/meta?key=用户key

返回结果：

{"data": {"page_no": 1,"page_size": 20,"rs_list": [{"adcode": "0","alert_condition": "","center": "116.48231,39.990177","create_time": "2017-01-16 17:49:51","enable": "false","fixed_date": "","gid": "7a6b40c6-7ba6-47e0-9b30-00354797c623","id": "0","key": "用户key","name": "fencetest","points": "","radius": 3000,"repeat": "Mon","time": "11:30,13:15;14:00,17:45","valid_time": "2017-01-22"}],"total_record": 1},"errcode": 0,"errmsg": "OK"}

上述示例中，查询对应用户key下的所有围栏，返回了一个已经创建的圆形围栏。

更新围栏

更新围栏API服务PATCH请求地址：curl -i -X PATCH https://restapi.amap.com/v4/geofence/meta?key=key&gid=gid -d 'json'

等价于curl -i -X POST https://restapi.amap.com/v4/geofence/meta?key=key&gid=gid&method=patch -d 'json'

请将json参数添加到body体中发送。query请求参数

key：用户唯一标识，必填。用户在高德地图官网申请Web服务API类型Key

gid：围栏全局id，必填。创建或查询围栏后高德返回的结果。json请求参数

参数名含义规则说明是否必填缺省值

name围栏名称字母&数字&汉字必填无

center圆形围栏中心点longitude,latitude圆形围栏必填与points互斥无

radius圆形围栏半径单位：米。范围0~5000。圆形围栏必填与points互斥无

points多边形围栏坐标点lon1,lat1;lon2,lat2;lon3,lat3(3<=点个数<=5000)。多边形围栏外接圆半径最大为5000米。多边形围栏必填无

enable围栏监控状态布尔类型可选true

valid_time过期日期围栏有效截止日期，过期后不对此围栏进行维护(围栏数据过期删除)；

不能设定创建围栏时间点之前的日期；

格式yyyy-MM-dd； 请设置2055年之前的日期可选创建时间后90天；

repeat一周内围栏监控日期的重复模式星期缩写列表，用","或“;”隔开。

样例："Mon,Sat"

表示周一和周六有效。

星期简称如下(首字母大写)：

Mon,Tues,Wed,Thur,Fri,Sat,Sun

repeat和fixed_date不能同时缺省或同时为空，二者所指出的监控日期为“或”关系可选，repeat和fixed_date不能同时缺省或同时为空，二者所指出的监控日期为“或”关系无

fixed_date指定日期列表格式"date1;date2;date3"； date格式"yyyy-MM-dd"；

最大个数180，不能设定过去日期；

repeat和fixed_date不能同时缺省或同时为空，二者所指出的监控日期为“或”关系；可选，repeat和fixed_date不能同时缺省或同时为空，二者所指出的监控日期为“或”关系无

time一天内围栏监控时段开始时间和结束时间定义一时间段，可设置多个时间段，时间段按照时间顺序排列，各时间段不可重叠；

拼接字符串格式如："startTime1,endTime1;startTime2,endTime2"；

最大个数24；

不可为空；

范围00:00-23:59；

时间段不可重叠；

时间段长度>15min；可选默认为00:00,23:59；

desc围栏描述信息可选无

alert_condition配置触发围栏所需动作触发动作分号分割

enter;leave(进入、离开触发)可选无返回结果参数说明

名称含义

data返回数据内容消息体

message状态说明信息

status状态值

errcode错误码

errmsg错误描述信息服务示例

请求PATCH地址：https://restapi.amap.com/v4/geofence/meta?key=用户key&gid=e7859ac4-4e57-4078-bb1a-d940b0158b4d

请求json参数：{"name": "更新圆形围栏","center": "116.328037,39.962379","radius": "1148.8","valid_time": "2017-06-30","repeat": "Mon,Wed,Fri,Sat,Sun","time": "07:00,12:00;15:00,21:00","desc": "更新圆形围栏描述","alert_condition": "enter"}

返回结果：{"data": {"message": "成功","status": "0"},"errcode": 0,"errmsg": "OK"}

上述示例中，更新了一个圆形围栏。成功后，返回了更新结果。

围栏启动&停止

更新围栏API服务PATCH请求地址：curl -i -X PATCH https://restapi.amap.com/v4/geofence/meta?key=key&gid=gid -d 'json'

等价于curl -i -X POST https://restapi.amap.com/v4/geofence/meta?key=key&gid=gid&method=patch -d 'json'

请将json参数添加到body体中发送。query请求参数

key：用户唯一标识，必填。用户在高德地图官网申请Web服务API类型Key

gid：围栏全局id，必填。创建或查询围栏后高德返回的结果。json请求参数

参数名含义规则说明是否必填缺省值

enable围栏激活状态；不能与更新围栏参数同时存在布尔类型可选true返回结果参数说明

名称含义

data返回数据内容消息体

message状态说明信息

status状态值

errcode错误码

errmsg错误描述信息服务示例

请求PATCH地址：https://restapi.amap.com/v4/geofence/meta?key=用户key&gid=e7859ac4-4e57-4078-bb1a-d940b0158b4d

请求json参数：{"enable": "false"}

返回结果：{"data": {"message": "成功","status": "0"},"errcode": 0,"errmsg": "OK"}

上述示例中，将对应的围栏激活状态置为false。成功后，返回了更新结果。

删除围栏

更新围栏API服务DELETE请求地址：curl -i -X DELETE https://restapi.amap.com/v4/geofence/meta?key=key&gid=gid

等价于curl -i -X POST https://restapi.amap.com/v4/geofence/meta?key=key&gid=gid&method=delete -d 'json'

请将json参数添加到body体中发送。query请求参数

key：用户唯一标识，必填。用户在高德地图官网申请Web服务API类型Key

gid：围栏全局id，必填。创建或查询围栏后高德返回的结果。返回结果参数说明

名称含义

data返回数据内容消息体

message状态说明信息

status状态值

errcode错误码

errmsg错误描述信息服务示例

请求DELETE地址：https://restapi.amap.com/v4/geofence/meta?key=用户key&gid=0cc9ea2c-191c-4f99-a49d-5a9fb5846d93

返回结果："data": {"message": "成功","status": "0"},"errcode": 0,"errmsg": "OK"}

上述示例中，将对应的围栏进行删除操作。成功后，返回了操作结果。

围栏设备监控

查询设备与附近的围栏交互状态。例如是否在围栏中，是否进出围栏；若未在围栏中，返回最近围栏的信息等。

API服务GET请求地址：https://restapi.amap.com/v4/geofence/statusquery请求参数

参数名含义规则说明是否必填缺省值

key请求服务权限标识用户在高德地图官网申请的开发者key必填无

diu用户设备唯一标识符设备唯一标识符，作为记录依据，不影响判断结果。Android设备一般使用imei号码，iOS一般使用idfv号，其余设备可根据业务自定义。必填无

uid设备在开发者自有系统中的id可选无

locations设备位置坐标组数据为坐标数据和坐标产生的时间戳数据，至少包含一个坐标对和时间戳。

1、传入1个点时，直接判断交互关系。

2、当传入多个点时，可以通过前后时间判断动态交互关系。

格式: x1,y1,unix_ts1;x2,y2,unix_ts2

动态交互判断方法：第一个点作为当前时间的点，然后从其余点中选出在当前点之前10s～1小时范围内的最早点，用这两个时间点的位置判断设备与围栏的动态交互关系。若数据无效交互关系默认返回leave。必填无

sig签名否无

返回结果参数说明

参数名含义

data返回数据内容消息体

status返回状态码

fencing_event_list围栏事件列表

client_action设备行为。对应3种与围栏的动态交互关系，进/出/停留： enter|leave|stay

client_status设备状态。当前与围栏的静态关系状态。是否在围栏里： in|out

enter_time用户进入围栏时间。格式： yyyy-MM-dd HH:mm:ss

fence_info围栏信息

fence_gid全局围栏id

fence_name围栏名称

nearest_fence_distance围栏距离设备的距离，没有命中围栏时返回。单位：米

当设备不在围栏中时，会返回最近围栏信息以及用户与这个围栏的距离，如果与最近围栏距离大于2000m，则该距离默认返回2000m。

nearest_fence_gid最近的围栏id

errcode错误码

errmsg错误消息服务示例

请求GET地址：https://restapi.amap.com/v4/geofence/status?key=用户key7&diu=设备imei&locations=116.472407,39.993322,1484816232

返回结果：

{"data": {"fencing_event_list": [{"client_action": "enter","client_status": "in","enter_time": "2017-01-19 16:57:12","fence_info": {"fence_center": "116.47253,39.992912","fence_gid": "31c94518-4145-4a94-9e7d-34cb027b4c96","fence_name": "测试大围栏"}}],"status": 0},"errcode": 0,"errmsg": "OK"}

上述示例中，查询对应的设备与已经创建的围栏关系，返回设备在一个围栏中，以及与这个围栏的交互关系。