地理围栏 最后更新时间: 2021年02月07日

温馨提示

目前平台已上线能力更全面，体验更流畅的新围栏服务，建议使用地理围栏服务的开发者使用新的地理围栏服务。

产品介绍

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

适用场景

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

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

使用限制

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

使用说明

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

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

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

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

接口对应的请求方式：

创建围栏

创建地理围栏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请求参数

• 返回结果参数说明

• 服务示例

请求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请求参数

• 返回结果参数说明

• 服务示例

请求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请求参数

• 返回结果参数说明

• 服务示例

请求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请求参数

• 返回结果参数说明

• 服务示例

请求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，必填。创建或查询围栏后高德返回的结果。

• 返回结果参数说明

• 服务示例

请求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请求参数

• 返回结果参数说明

• 服务示例

请求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"

}

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