> For the complete documentation index, see [llms.txt](https://adatrack.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://adatrack.gitbook.io/docs/documentation/features/geofencing.md).

# Geofencing

Geofencing allows you to define virtual perimeters on a map and receive real-time alerts when your IoT devices enter or leave these boundaries. This is a critical feature for security, asset recovery, and operational efficiency.

### What is a Geofence?

A **Geofence** in AdaTrack is a polygon-shaped area defined by its geographic coordinates. You can draw these shapes directly on the live map using our intuitive drawing tools.

### Key Capabilities

* **Polygon Support:** Create complex, multi-sided boundaries to match real-world locations like warehouses, construction sites, or delivery zones.
* **Real-time Monitoring:** Every incoming telemetry packet with a valid GPS coordinate is automatically checked against your active geofences.
* **Entry & Exit Triggers:** Configure alerts to fire when a device enters a zone, leaves a zone, or both.
* **Stateful Alerting:** AdaTrack remembers if a device is currently "Inside" or "Outside" a fence. This prevents "alert storms" (duplicate notifications) if a device sends multiple packets while staying within the same area.
* **Multi-Device Rules:** Link a single geofence to an entire **Device Profile** or a specific list of individual devices.

### Setting Up Geofencing

#### 1. Create a Geofence

1. Navigate to the **Geofencing** page.
2. Use the **Polygon Tool** to draw your boundary on the map.
3. Give your geofence a name (e.g., "Main Warehouse") and save it.

#### 2. Configure a Notification Channel

Before you can receive alerts, you need to tell AdaTrack where to send them.

1. Go to **Alert Channels**.
2. Add a new channel (e.g., **Slack**, **Webhook**, or **Telegram**).
3. Enter the required configuration (e.g., Slack Webhook URL).

#### 3. Create an Alert Rule

Link your geofence to your notification channel.

1. In the **Alert Rules** tab, click **Create Rule**.
2. Select the **Geofence** you created.
3. Choose the **Trigger Condition** (Enter, Exit, or Both).
4. Select the **Notification Channel** to use.
5. Save the rule.

### Technical Details (For Developers)

* **Spatial Engine:** AdaTrack uses **PostGIS** and the `ST_Contains` function for high-performance spatial lookups.
* **GIST Indexing:** Our geofence table is indexed using GIST (Generalized Search Tree) to ensure that spatial queries remain fast even with thousands of active perimeters.
* **Asynchronous Processing:** Geofence checks happen asynchronously in a separate worker pool. This ensures that the high-throughput UDP ingestion path is never blocked by spatial analysis.

### Best Practices

* **Avoid Overlapping Fences:** While AdaTrack supports overlapping geofences, it can lead to confusing notifications if a device triggers multiple rules simultaneously.
* **Mind the GPS Accuracy:** Small geofences (e.g., < 10 meters) may trigger false alerts if the device's GPS signal has high jitter or poor accuracy. We recommend a minimum buffer of 20-50 meters for reliable alerting.
* **Use Clear Names:** Name your geofences based on their real-world location to make notifications more actionable for your team.