MTS Geofences

introduction 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 mts geofence mts also has the functionality of sending a notification once the location of a gps device is close to a mentioned geographic location you can create a new geofence entry in the database for which the notification is to be sent when the gps device approaches the location how it works 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 apis related to the geofence feature creategeofence creates a geofence updategeofencestatus deactivates or reactivates a geofence deletegeofence deletes a geofence getgeofence retrieves a geofence getgeofencebyexternalrefid retrieve a specific geofence using a unique externalrefid subscribedevices subscribes device(s) to geofenceid getsubscribeddevices fetches devices subscribed to a geofenceid getsubscribeddevice retrieve a device subscribed to a geofenceid unsubscribedevice unsubscribe devices subscribed to a geofenceid updatetracedata updates trace data use cases 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 integration flow 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 step 1 create a geofence 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 https //datatracker ietf org/doc/html/rfc7946#section 3 1 6 parameter description name the name of the geofence geojson geofence details in geojson format the api follows the geojson standard for polygons https //datatracker ietf org/doc/html/rfc7946#section 3 1 6 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, expressed in \[lon, lat] format note this follows the \[longitude, latitude] convention, which differs from the common \[latitude, longitude] format 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 point { "name" "storegeofence2", "geojson" { "type" "featurecollection", "features" \[ { "type" "feature", "properties" { "description" "geofence for store xyz", "radius" 1000 }, "geometry" { "type" "point", "coordinates" \[77 21875869283741, 28 632319404674092] } } ] } } polygon { "name" "storegeofence", "geojson" { "type" "featurecollection", "features" \[ { "type" "feature", "properties" { "description" "geofence for store xyz", "radius" 300 }, "geometry" { "type" "polygon", "coordinates" \[ \[ \[ 121 923828125, 37 398384033203124], \[ 121 4609375, 37 25603309024043], \[ 121 240234375, 37 85473410511505], \[ 122 1484375, 38 041800661245646], \[ 122 265625, 37 52916159927411], \[ 121 923828125, 37 398384033203124] ] ] } } ] }, "description" "geofence for store xyz" } the response includes the geofenceid which you’ll use to subscribe devices to the geofence "data" { "geofenceid" "3e3d63c5 9db4 11eb 9534 f80dac4a6ad0" } step 2 get geofence after successfully creating a geofence, you can retrieve the its details by passing the geofenceid or externalrefid using the following endpoints getgeofence getgeofencebyexternalrefid upon success, the api returns the geofence name, description, and perimeter coordinates see an example response below { "request" { "body" {}, "querystring" "", "uri" "/geofences/3e3d63c5 9db4 11eb 9534 f80dac4a6ad0" }, "error" { "additionalinfo" {}, "code" 0, "description" "" }, "data" { "name" "warehouse a", "geojson" { "type" "featurecollection", "features" \[ { "type" "feature", "properties" { "radius" 500 }, "geometry" { "coordinates" \[ \[ \[77 5174, 12 9359], \[77 5178, 12 9358], \[77 5176, 12 9353], \[77 5171, 12 9354], \[77 5174, 12 9359] ] ], "type" "polygon" } } ] }, "description" "main warehouse", "externalrefid" "warehouse123", "geofenceid" "3e3d63c5 9db4 11eb 9534 f80dac4a6ad0", "geofencestatus" "active", "createdby" "user\@example com", "createdat" 1649754846000, "updatedby" "user\@example com", "updatedat" 1649754846000, "isactive" true, "radius" 500, "expiresat" 1649761046000 } } external ref id { "request" { "body" {}, "querystring" "", "uri" "/geofences/warehouse123" }, "error" { "additionalinfo" {}, "code" 0, "description" "" }, "data" { "name" "warehouse a", "geojson" { "type" "featurecollection", "features" \[ { "type" "feature", "properties" { "radius" 500 }, "geometry" { "coordinates" \[ \[ \[77 5174, 12 9359], \[77 5178, 12 9358], \[77 5176, 12 9353], \[77 5171, 12 9354], \[77 5174, 12 9359] ] ], "type" "polygon" } } ] }, "description" "main warehouse", "externalrefid" "warehouse123", "geofenceid" "3e3d63c5 9db4 11eb 9534 f80dac4a6ad0", "geofencestatus" "active", "createdby" "user\@example com", "createdat" 1649754846000, "updatedby" "user\@example com", "updatedat" 1649754846000, "isactive" true, "radius" 500, "expiresat" 1649761046000 } } step 3 subscribe devices 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 30 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 " https //myapp com/notify https //myapp com/notify " 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 { "deviceid" \[ "5000392730074", "9000561266227" ], "callback" { "url" "https //webhook site/01652cf7 1c03 4c4a a57f 60b245dde32d", "meta" {} }, "expiry" "1d4h3m", "geofencetype" "entry" } the response includes a message indicating if the subscription was a success or failure if the request fails, an error reason will be provided step 4 send device traces 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 { "lat" 77 21875869283741, "lon" 28 632319404674092, "tis" 1626414000000, "seq" 1, "accuracy" 20, "provider" "gps", "speed" 0 05 } step 5 get geofence events 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 { "data" { "tenantid" "string", "geofenceid" "string", "action" "entered", "deviceid" "string", "app" "string", "lat" 0, "lon" 0, "actiontis" 0 }, "meta" {} }