MTS Geofences
MTS GeoFence provides a simple way of creating geofences by specifying latitude, longitude, radius, or a geojson polygon. This feature empowers app developers to set up geofences and receive alerts when a designated device enters or exits a specific geofence. Developers can use geofencing while building apps related to fleet tracking and last-mile delivery.
Geofencing involves creating virtual boundaries or geofences and associating devices with the Geofences in order to receive notifications whenever devices enter or exit them. Once the location trace data of a device is sent to MTS, the Geofence feature checks if the location falls within the associated geofence. If yes, then the applications are notified through a callback URL.
The MTS Geofence technology utilizes location-based notifications, alerts, and automation for tracking, monitoring, managing access, and facilitating communication. Here are a few typical use cases:
- Food Delivery Alerts: Notifies customers when the delivery driver nears a set distance from their address, making food delivery more efficient.
- Fleet Operations & Shuttle Services: In fleet operations like shuttle services, alert drivers when they leave their assigned region or territory.
- Restricted Zones in Urban Areas: Set geofences around no-entry zones in areas with vehicle restrictions so drivers and dispatchers receive immediate alerts if their trucks venture into the restricted areas.
- Monitoring Facility Entry and Exit Points: Set up geofences that monitor all vehicular movements in and out of a facility such as a warehouse. By linking these geofences with a unique external reference IDs, you can receive alerts when vehicles enter or exit the facility.
Integrating Geofence with your applications involves the below five-steps:
- Create Geofences: Initiate geofencing by creating circular or polygonal geofences using CreateGeofence.
- Get Geofence Details: Retrieve geofence details by passing the geofencId.
- Subscribe Devices: Use the SubscribeDevices API to link the devices that you want to monitor with the created geofences. In addition, specify the callback URL to receive notification.
- Send Device Traces: Use the UpdateTraceData to send trace data to MTS for device tracking within the Geofence.
- Receive and Monitor Notifications: Upon a device's entry or exit from a geofence, the MTS geofence feature sends a notification to the callback URL you've set up.
Follow the steps below to start using geofences for location-based alerts:
Use the CreateGeofences request to create circular or polygonal geofences. View the request parameters below. Note that when creating a polygon geofence, the API follows the geojson standard for polygons.
Parameter | Description |
|---|---|
name | The name of the geofence |
geojson | Geofence details in GeoJSON format. The API follows the geojson standard for polygons. |
geojson.type | Type of the feature collection |
geojson.features | Array containing geojson features |
geojson.features.type | Type of the geojson feature |
geojson.features.properties | Metadata about the feature |
geojson.features.properties.radius | Radius of geofence in meters |
geojson.features.geometry | Geometry of the geofence |
geojson.features.geometry.coordinates | Coordinates of the geofence boundary |
description | Description for the geofence |
externalRefId | An optional attribute that the developers can use to associate the Geofence with their own IDs |
Refer to the examples below for creating Point and Polygon geofences.
The response includes the geofenceId which you’ll use to subscribe devices to the geofence.
After successfully creating a geofence, you can retrieve the its details by passing the geofenceId or externalRefId using the following endpoints:
Upon success, the API returns the geofence name, description, and perimeter coordinates. See an example response below.
Use the SubscribeDevices to register devices to the geofence. You’ll need the geofenceId from the GetGeofence request, the deviceIds associated with your application, and the callback URL to receive geofence notifications. View the request parameters below.
Parameter | Data Type | Description | Example |
|---|---|---|---|
deviceId* | array | Array of device IDs to subscribe to geofence | ["5000392730074", "9000561266227"] |
expiry | string | The time after the geofence-device mapping expires. Maximum allowed value is 60 days. If not provided, then geofence-device subscription will not expire. | 2hour -> 2h, 1day -> 1d, 50seconds -> 50s, 3hours,4mins,7s -> 3h4m7s |
geofenceType | string | Notification type - "entry", "exit" or "both" | "both" |
callback | object | Callback object | |
callback.url* | string | Callback URL to receive notifications | |
callback.meta | object | Additional metadata object for callback body | {"version":"1.0"} |
callback.secret | string | base64 encoded HMAC secret key | "c2VjcmV0a2V5" |
The following request specifies two device IDs to subscribe to, with an expiry set for one day. Additionally, the geofenceType is set to "both," which enables notifications for both entry and exit from the specified geofences that will be sent to the callback URL specified in the request.
The response includes a message indicating if the subscription was a success or failure. If the request fails, an error reason will be provided.
After subscribing a device to a geofence, the device should send data using the InsertTraceDataByTrackName or InsertTraceDataByTrackId request for apps to receive entry and exit events. This alert includes information such as the geofence and device IDs, as well as the type of transition observed.
Path Parameters
Parameters | Description |
|---|---|
trackName | The name of the track. |
trackId | The track id. |
Body Parameters
Parameter | Data Type | Description | Data type |
|---|---|---|---|
lat* | number | Latitude | 17..456 |
lon* | number | Longitude | 76.456 |
tis* | integer | Timestamp of trace event in milliseconds | 1626413830000 |
seq | integer | Sequence number of trace event | 2 |
id | string | List of strings that contains the dispatchId, etc., to help keep track of the device-dispatch mapping | 020d0755-8aeb-47b4-a327-deeaf64bf816 |
speed | number | Speed in km | 0.05 |
provider | string | Depicts whether the location data is coming from gps or any other source | gps |
accuracy | number | Accuracy | 20 |
event | string | Event consisting of device details | string |
event.name | string | Event name being sent | string |
event.data | string | Dynamic data sent in the event | string |
Example Request
The following example demonstrates the insertion of an entry and exit trace for the polygon geofence.
Note: Note that the example below includes a static time stamp. When making your request, keep in mind that the MTS API requires timestamps to be in a 48 hour period.
For each fetched geofenceId, the MTS Geofence feature will check if the coordinates of the device lie inside the polygon. Based on the device’s position, an entry and exit notification will be sent via the callback method specified in the device registration to the geofence.
The callback payload structure for the callback is specified below: