seo_title: "Geofencing API – Hàng rào ảo & cảnh báo ra vào | VIETMAP" description: "Vẽ hàng rào ảo ở bất kỳ đâu tại Việt Nam và phát hiện khi xe hoặc thiết bị ra vào vùng đó — dùng để xác nhận giao hàng và giám sát đội xe." keywords: geofencing api, geofence api, virtual boundary api, enter exit detection, API hàng rào địa lý, geofencing là gì, cảnh báo ra vào vùng, giám sát đội xe
Geofencing API — Hàng rào địa lý ảo¶
Geofencing là vẽ một hàng rào ảo quanh một địa điểm thật rồi phản ứng khi thiết bị hoặc xe đi qua ranh giới đó. Geofencing API của VIETMAP cho phép bạn khai các hàng rào này ở bất kỳ đâu tại Việt Nam và đối chiếu vị trí với chúng, nhờ vậy việc vào hoặc ra khỏi một vùng có thể kích hoạt thông báo, cảnh báo, hoặc một bước trong quy trình của bạn.
Dùng vào việc gì¶
| Bài toán | Hàng rào ảo làm gì |
|---|---|
| Xác nhận giao hàng | Kiểm chứng xe đã thật sự tới địa chỉ khách trước khi tài xế bấm hoàn tất đơn. |
| Giám sát tuân thủ đội xe | Cảnh báo khi xe tải ra khỏi vùng được phép chạy hoặc đi vào khu vực bị cấm. |
| Tự động ghi nhận chuyến | Tự mở và đóng sổ chuyến khi xe rời kho và quay về, tài xế không phải thao tác gì. |
| Chấm công tại chỗ | Ghi nhận nhân viên tới và rời công trường hoặc chi nhánh. |
| Tiếp thị theo vị trí | Gửi thông báo khi khách đang ở gần một cửa hàng của bạn. |
| Bảo vệ tài sản | Báo động ngay khi thiết bị bị đưa ra khỏi bãi của nó. |
Geofence khác isochrone thế nào¶
Geofence là hàng rào do bạn tự vẽ rồi theo dõi ai ra vào. Còn isochrone là vùng do VIETMAP tính giúp bạn — vùng đi tới được trong một khoảng thời gian cho trước. Hai thứ này ghép với nhau rất tự nhiên: tính isochrone để biết vùng phục vụ hợp lý trông thế nào, rồi khai chính vùng đó thành geofence và theo dõi.
URL¶
Method¶
POST
Tham số¶
| Tham số | Kiểu | Bắt buộc | Mặc định | Mô tả |
|---|---|---|---|---|
| apikey | string | có | không | API key VIETMAP cấp cho tài khoản của bạn. Đăng ký API key |
Ví dụ¶
Body:
{
"geometryCenters":
[
{
"id": "1",
"long": 105.7487405,
"lat": 9.8644254
},
{
"id": "2",
"long": 105.7491342,
"lat": 9.8642686
},
{
"id": "3",
"long": 105.7489267,
"lat": 9.8645398
}
],
"radius": 15,
"long": 105.7488398,
"lat": 9.8643837
}
curl -X POST 'https://maps.vietmap.vn/api/geofencing?apikey=YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"geometryCenters":[{"id":"1","long":105.7487405,"lat":9.8644254},{"id":"2","long":105.7491342,"lat":9.8642686},{"id":"3","long":105.7489267,"lat":9.8645398}],"radius":15,"long":105.7488398,"lat":9.8643837}'
// Node.js 18+. Gọi từ server để không lộ API key.
const body = {
"geometryCenters": [
{
"id": "1",
"long": 105.7487405,
"lat": 9.8644254
},
{
"id": "2",
"long": 105.7491342,
"lat": 9.8642686
},
{
"id": "3",
"long": 105.7489267,
"lat": 9.8645398
}
],
"radius": 15,
"long": 105.7488398,
"lat": 9.8643837
};
const res = await fetch("https://maps.vietmap.vn/api/geofencing?apikey=YOUR_API_KEY", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(body),
});
const data = await res.json();
console.log(data);
import requests
body = {
"geometryCenters": [
{
"id": "1",
"long": 105.7487405,
"lat": 9.8644254
},
{
"id": "2",
"long": 105.7491342,
"lat": 9.8642686
},
{
"id": "3",
"long": 105.7489267,
"lat": 9.8645398
}
],
"radius": 15,
"long": 105.7488398,
"lat": 9.8643837
}
resp = requests.post("https://maps.vietmap.vn/api/geofencing?apikey=YOUR_API_KEY", json=body, timeout=30)
resp.raise_for_status()
print(resp.json())
Tích hợp VIETMAP Geofencing API vào dự án của tôi.
Request mẫu (theo ví dụ trong tài liệu):
POST https://maps.vietmap.vn/api/geofencing
Body (JSON): {"geometryCenters":[{"id":"1","long":105.7487405,"lat":9.8644254},{"id":"2","long":105.7491342,"lat":9.8642686},{"id":"3","long":105.7489267,"lat":9.8645398}],"radius":15,"long":105.7488398,"lat":9.8643837}
Yêu cầu:
- Gọi API từ server. Đọc API key từ biến môi trường VIETMAP_API_KEY và truyền qua `apikey`, không ghi cứng trong code.
- Viết một hàm gửi request này, kiểm tra mã HTTP và trả về dữ liệu đã parse.
- Đọc tài liệu bên dưới trước. Chỉ dùng tham số và trường dữ liệu có trong tài liệu.
Tài liệu:
- https://maps.vietmap.vn/docs/vi/map-api/geofencing/index.txt
- https://maps.vietmap.vn/docs/assets/agents/logistics.txt
Mô tả tham số¶
| Trường | Kiểu | Mô tả |
|---|---|---|
| geometryCenters | array | Danh sách tâm vùng cần đối chiếu, mỗi phần tử một vùng. |
| geometryCenters.id | string | Mã định danh của tâm vùng. |
| geometryCenters.long | number | Kinh độ của tâm vùng. |
| geometryCenters.lat | number | Vĩ độ của tâm vùng. |
| radius | number | Bán kính (mét), áp cho mọi tâm trong geometryCenters. Vị trí cách tâm không quá radius thì inside = true. |
| long | number | Kinh độ của vị trí cần kiểm tra (xe, thiết bị). |
| lat | number | Vĩ độ của vị trí cần kiểm tra (xe, thiết bị). |
Phản hồi¶
{
"code": null,
"message": null,
"data": [
{
"id": "1",
"inside": true
},
{
"id": "2",
"inside": false
},
{
"id": "3",
"inside": false
}
]
}
Mô tả phản hồi¶
| Trường | Kiểu | Mô tả |
|---|---|---|
| code | null | Mã lỗi. null khi thành công. |
| message | null | Thông báo lỗi. null khi thành công. |
| data | array | Một phần tử cho mỗi tâm trong geometryCenters. |
| data.id | string | id bạn đã gửi cho tâm vùng đó. |
| data.inside | boolean | true nếu vị trí cách tâm này không quá radius, ngược lại false. |
API liên quan¶
- Map Matching — dựng lại tuyến đã chạy từ cùng nguồn GPS.
- Reverse v4 — địa chỉ tại vị trí của xe.
- VRP — lập kế hoạch các điểm giao mà geofence sẽ xác nhận.
