Geofences API
Manage geographical boundaries for asset monitoring and event triggering.
Overview
Geofences are virtual perimeters defined by geographical coordinates. They enable location-based triggers for monitoring asset movements and generating alerts when assets enter or exit specific areas.
Geofence Object Fields
| Field | Type | Description |
|---|---|---|
id | String | Unique identifier for the geofence. Auto-generated UUID if not provided. |
type | String | Geometry type: circle, rectangle, or polygon. |
name | String | Human-readable name for the geofence. |
geometry | Object | Geometry definition containing coordinates for the virtual boundary area. |
keywords | Array | List of keywords for searching and filtering geofences. |
properties | Object | Custom JSON properties for additional metadata. |
created_at | Integer | Unix timestamp when the geofence was created. |
updated_at | Integer | Unix timestamp when the geofence was last updated. |
Geofence Types
The API supports three geometry types:
- Circle - Defined by center point and radius
- Rectangle - Defined by min/max longitude and latitude
- Polygon - Defined by an array of coordinate points
Add or Update Geofence Areas
Create or update geofences with custom properties and keywords for filtering.
-
Endpoint:
POST /add_geofence_area -
Headers:
Authorization: YOUR_API_KEYContent-Type: application/jsonAccept: application/json
-
Request Body:
{
"geofences": [
{
"p_id": "downtown_delivery_zone",
"p_type": "polygon",
"p_name": "Downtown Delivery Zone",
"p_keywords": ["delivery", "downtown", "high-priority"],
"p_properties": {
"zone_type": "commercial",
"business_hours": "9AM-5PM"
},
"p_geojson": {
"type": "Polygon",
"coordinates": [[[25.612887, 45.647265], ...]]
}
}
]
}
Parameters:
p_id(optional) - Custom identifier (UUID auto-generated if not provided)p_type- Geometry type:circle,rectangle, orpolygonp_name(optional) - Human-readable namep_keywords(optional) - Array of search/filter keywordsp_properties(optional) - Custom JSON propertiesp_geojson- GeoJSON geometry definition
Batch Operations:
You can add up to 1,000 geofences per request.
- Response Body: (code
200 OK)
{
"geofence_ids": [
{
"id": "downtown_delivery_zone",
"error": ""
}
]
}
Get Geofences
Retrieve geofence details by IDs or search by keywords.
Get by IDs
-
Endpoint:
GET /get_geofence_areas -
Headers:
Authorization: YOUR_API_KEYContent-Type: application/jsonAccept: application/json
-
Request Body:
{
"p_ids": ["downtown_delivery_zone", "warehouse_safety_zone"]
}
- Response Body: (code
200 OK)
{
"type": "FeatureCollection",
"features": [
{
"id": "downtown_delivery_zone",
"name": "Downtown Express Delivery Zone",
"type": "Feature",
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
25.6128875,
45.647265312
],
...
]
]
},
"keywords": [
"delivery",
"downtown",
"express",
"priority-shipping"
],
"created_at": 1766477749,
"properties": {},
"updated_at": 1766477809,
"type_geofence": "polygon"
},
...
]
}
Get by Keywords
-
Endpoint:
GET /get_geofences_by_keywords -
Headers:
Authorization: YOUR_API_KEYContent-Type: application/jsonAccept: application/json
-
Request Body:
{
"p_keywords": ["warehouse"],
"p_min_longitude": 25.59,
"p_min_latitude": 45.64,
"p_max_longitude": 25.63,
"p_max_latitude": 45.66,
"p_page_no": 1,
"p_entries_per_page": 1000
}
Optional Bounding Box Filter:
Use p_min_longitude, p_min_latitude, p_max_longitude, p_max_latitude to restrict results to a specific area.
- Response Body: (code
200 OK)
{
"data": {
"type": "FeatureCollection",
"features": [
{
"id": "warehouse_safety_perimeter",
"name": "Warehouse Complex - All Buildings",
"type": "Feature",
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
25.609,
45.644
],
...
]
]
},
"keywords": [
"warehouse",
"safety",
"restricted-area",
"all-buildings",
"security-zone"
],
"created_at": 1766477749,
"properties": {
"alert_on_exit": 1,
"facility_name": "Main Distribution Complex",
"alert_on_entry": 1,
"security_level": "maximum",
"updated_reason": "Expanded to include new buildings B and C",
"24_7_monitoring": 1,
"buildings_covered": [
"A",
"B",
"C"
],
"emergency_contact": "+1-555-0123"
},
"updated_at": 1766477789,
"type_geofence": "rectangle",
"rectangle_max_xy": [
25.615,
45.648
],
"rectangle_min_xy": [
25.609,
45.644
]
},
{
"id": "warehouse_safe_zone",
"name": "Warehouse Safety Perimeter",
"type": "Feature",
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
25.614488063,
45.647016778
],
...
]
]
},
"keywords": [
"warehouse",
"safety",
"restricted"
],
"created_at": 1766477759,
"properties": {},
"updated_at": 1766477759,
"circle_center": [
25.6119221881739,
45.6469856317244
],
"circle_radius": 200,
"type_geofence": "circle"
},
{
"id": "warehouse_safe_zone_2",
"name": "Warehouse Safety Perimeter",
"type": "Feature",
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
50.267728413,
43.217720583
],
...
]
]
},
"keywords": [
"warehouse",
"safety",
"restricted"
],
"created_at": 1768298985,
"properties": {},
"updated_at": 1768299009,
"circle_center": [
25.6740261509171,
46.3769791691117
],
"circle_radius": 1992157,
"type_geofence": "circle"
}
]
},
"page": {
"total_entries": 3,
"offset_entries": 0,
"total_pages": 1,
"page_no": 1,
"entries_per_page": 1000,
"has_more": false
}
}
Get Proximity Geofences
Find geofences near a specific location within a given distance.
-
Endpoint:
GET /get_geofence_proximity_areas -
Headers:
Authorization: YOUR_API_KEYContent-Type: application/jsonAccept: application/json
-
Request Body:
{
"p_location": [25.612211, 45.647781],
"p_limit_count": 10,
"p_distance_tolerance_m": 1000,
"p_keywords": ["parking", "warehouse"]
}
-
Parameters:
p_location- [longitude, latitude] coordinatesp_limit_count- Maximum number of results to returnp_distance_tolerance_m- Search radius in metersp_keywords(optional) - Filter by keywords
-
Response Body: (code
200 OK)
[
{
"id": "employee_parking_lot",
"name": "Employee Parking Area",
"contains_point": false,
"distance_to_border": -415.75
},
{
"id": "parking_lot_area",
"name": "Employee Parking Zone (Circular)",
"contains_point": false,
"distance_to_border": -416.34
}
]
Distance Interpretation:
- Negative value - Point is outside the geofence (distance to nearest border)
- Positive value - Point is inside the geofence (distance from nearest border)
- Zero - Point is exactly on the geofence boundary
Use Cases:
- Finding nearby parking zones
- Locating closest service areas
- Detecting proximity to restricted zones
- Navigation assistance
Check Locations in Geofences
Determine if specific coordinates fall within geofences.
-
Endpoint:
GET /geofences_contain_locations -
Headers:
Authorization: YOUR_API_KEYContent-Type: application/jsonAccept: application/json
-
Request Body:
{
"p_geofence_ids": ["parking_lot_area", "warehouse_safe_zone"],
"p_locations": [
[25.608396, 45.636208],
[25.628249, 45.653283]
]
}
- Response Body: (code
200 OK)
{
"checked_geofences": [
{
"geofence_id": "parking_lot_area",
"locations": [
{
"index": 0,
"inside": false,
"distance_m": 642
}
]
}
]
}
Update Geofence
Modify existing geofence properties or geometry.
-
Endpoint:
PUT /update_geofence_area -
Headers:
Authorization: YOUR_API_KEYContent-Type: application/jsonAccept: application/json
-
Request Body:
{
"p_id": "downtown_delivery_zone",
"p_name": "Downtown Express Delivery Zone",
"p_keywords": ["delivery", "downtown", "express"]
}
Delete Geofences
Remove geofences by IDs or keywords.
-
Endpoint:
DELETE /remove_geofence_areas -
Headers:
Authorization: YOUR_API_KEYContent-Type: application/jsonAccept: application/json
-
Request Body:
{
"p_ids": ["old_zone_1"],
"p_keywords": ["deprecated"]
}
Notes
- Use meaningful
p_idandp_namevalues for easier management - Add descriptive keywords for efficient searching and filtering
API Limits
- Keep geofence areas under 1000 km²
- Add or update up to 1,000 geofences per batch request
- For requests that support pagination, entries per page can be set to maximum 1000