示例中心
功能在线体验
控制台
您现在的位置: 开发 > Web服务 API > 开发指南 > API文档 > 地理围栏 >

高德 开发 Web服务 API 开发指南 API文档 地理围栏

更新时间:2018年07月26日

产品介绍

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

适用场景

地理围栏服务适用于需要针对特定区域,监控用户位置与区域关系的场景中。包括但不限于:

  • 签到打卡类场景,在用户打卡操作前,判断用户是否已经在对应的地理围栏区域内;
  • 共享单车类场景,当用户骑车离开合法使用区域时,第一时间获知;或当用户关锁支付时,判断用户是否停在了合法区域内;
  • 线下门店促销场景,当获取到用户定位在促销门店区域的附近时,向用户发送引导进入店铺的促销信息。

使用限制

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

使用说明

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

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

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

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


接口对应的请求方式:

方法名称

请求方式

创建围栏

POST

查询围栏

GET

更新围栏

PATCH

围栏启动&停止

PATCH

删除围栏

DELETE

围栏设备监控

GET

创建围栏

创建地理围栏API服务POST请求地址:

curl -i -X POST http://restapi.amap.com/v4/geofence/meta?key=用户key -d 'json'

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

  • query请求参数

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

  • json请求参数

参数名

含义

规则说明

是否必填

缺省值

name

围栏名称

字母&数字&汉字

必填

center

圆形围栏中心点

longitude,latitude

圆形围栏必填与points互斥

radius

圆形围栏半径

单位:米。范围0~3000。

圆形围栏必填与points互斥 

points

多边形围栏坐标点

lon1,lat1;lon2,lat2;lon3,lat3(3<=点个数<=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

围栏id

message

状态说明信息

status

状态值

errcode

错误码

errmsg

错误描述信息

  • 服务示例

请求POST地址:

http://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 http://restapi.amap.com/v4/geofence/meta?key=用户key
  • query请求参数

参数名

含义

规则说明

是否必填

缺省值

key

请求服务权限标识

用户在高德地图官网申请Web服务API类型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地址:

 http://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 http://restapi.amap.com/v4/geofence/meta?key=key&gid=gid -d 'json'

等价于

curl -i -X POST http://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~3000。

圆形围栏必填与points互斥 

points

多边形围栏坐标点

lon1,lat1;lon2,lat2;lon3,lat3(3<=点个数<=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地址:

http://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 http://restapi.amap.com/v4/geofence/meta?key=key&gid=gid -d 'json'

等价于

curl -i -X POST http://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地址:

http://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 http://restapi.amap.com/v4/geofence/meta?key=key&gid=gid 

等价于

curl -i -X POST http://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地址:

 http://restapi.amap.com/v4/geofence/meta?key=用户key&gid=0cc9ea2c-191c-4f99-a49d-5a9fb5846d93

返回结果:

  "data": {
    "message": "成功",
    "status": "0"
  },
  "errcode": 0,
  "errmsg": "OK"
}

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

围栏设备监控

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

API服务GET请求地址:

http://restapi.amap.com/v4/geofence/status
  • query请求参数

参数名

含义

规则说明

是否必填

缺省值

key

请求服务权限标识

用户在高德地图官网申请的开发者key

必填

diu

用户设备唯一标识符

设备唯一标识符。Android为imei,iOS为idfv

必填

uid

设备在开发者自有系统中的id


可选

locations

设备位置坐标组

包含坐标数据和坐标产生的时间戳数据。 判定依据:最新的点 作为当前,然后从距离当前点10s~一小时 范围内选出最早点 

格式: x1,y1,unix_ts;x2,y2,unix_ts

必填。至少包含设备的一个坐标以及时间戳。当有多个坐标以及时间戳,可判断与围栏的进/出状态。

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

围栏距离设备的距离,没有命中围栏时返回。单位:米

nearest_fence_gid

最近的围栏id

errcode

错误码

errmsg

错误消息

  • 服务示例

请求GET地址:

http://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"
}

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


示例中心 功能
在线体验
常见问题