產品介紹

地理圍欄服務是一類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"}

上述示例中，查詢對應的設備與已經創建的圍欄關系，返回設備在一個圍欄中，以及與這個圍欄的交互關系。

總結

以上是生活随笔為你收集整理的设置电子围栏 高德地图_地理围栏-API文档-开发指南-Web服务 API | 高德地图API的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。