Device-based notifications
Action-Get
Return the latest 100 vehicle alerts across the account.
module=alerts&action=get
To access alerts from a specific time period or per device, use the Alerts report
Example request
https://app.trackmyride.com.au/v2/php/api.php?api_key=GF83FDSa72hds82jfFD82js123j3284mw8223&user_key=gtr873ns2eDSf111&module=alerts&action=get
Returned Data
| Name | Description | Example |
|---|---|---|
| If XML: data contained inside <data> | Array of objects | { created_at: "2021-09-23 17:24:13", description: "Exited the zone Track My Ride Heidelberg West. Current speed is 33 km/h", event_lat_lng: " {"lat":"-37.731930","lng":"145.048432","address":"32-36 Mologa Road, Heidelberg West, VIC"}", operator_name: "Sally Smith", unique_id: "b9e2a95a2b1e7489", vehicle_name: "TMR White" } |
Data included in returned data
For each row, the following data is included
| Name | Description |
|---|---|
| unique_id | The unique ID of the alert |
| created_at | Time the alert was raised in the device's local timezone. |
| created_at_epoch | Epoch time the alert was raised in the device's local timezone. |
| vehicle_name | The device that triggered the alert |
| vehicle_unique_id | The TMR unique_id of the device that triggered the alert |
| event_lat_lng | The location the device was at. A string conversion of a JSON object like { lat: -37.731930, lng: 145.048432, address: "32-36 Mologa Road, Heidelberg West, VIC", } |
| description | A text description of the alert |
| operator_name | The driver of the vehicle |
| acknowledged | If the alert is a panic/SOS event, this will return a JSON-encoded array of array containing the list of user's who have acknowledged the panic/SOS event. [ [user_unique_id: the user's unique_id that acknowledged the alert, utc_time: the time in YYYY-MM-DD HH:MM:SS format in UTC that the alert was acknowledged] ] |
Action-Save
Create or update an alert.
module=alerts&action=save
Required data
To update or create an Alert, send variables as query params or via form-data. Data is contained in the variable "data". For example, to set the variable "frequency" to 15, add data[frequency]=15 .
Updating
When updating an alert, if a variable is not supplied in the update request it will remain set to its current value.
Description of Alert data properties
| Variable | Type | Description | Required | Example |
|---|---|---|---|---|
| unique_id | string | Unique id for the alert to be updated, if updating an existing record. If you're creating a new record, don't pass this variable. One will be created for your new record and returned. | creating a new record : noupdating : yes | 7198bf67b5fd |
| frequency | int | The minimum frequency at which the alert can be triggered, in minutes. Note: this applies on a per-vehicle per-zone basis | yes | 15 |
| dayparts_ignore | array | An array of hours in a day to ignore the alert Days indexed from 0 to 6, with Sunday as 0 Hours indexed from 0 to 23, with 0 representing the entire hour of 12 am to 12:59:59 am | no defaults to full coverage | [{"day": "0", "hour": "10"}] |
| zones_limit | array | A set of zones in which the device must be in for the alert to trigger Given as an array of zone unique id’s | no defaults to none | ["yhjdsakf83jn", "dsagfgjh3a"] |
| zones_ignore | array | A set of zones in which the alert will be suppressed and not raised if the event occurs within. Given as an array of zone unique id’s | no defaults to none | ["yhjdsakf83jn", "dsagfgjh3a"] |
| vehicle_id | array or string | The set of devices the alert is being created for. Can be supplied as an array for multiple vehicles, or a string for a single vehicle Note: "*" can be used as a wildcard to trigger this alert for all vehicles | yes | ["3dfaf3af3j1", "843hf92n"] or ["*"] |
| string | The email/s the alert may be sent to Multiple emails are separated by a comma | no defaults to none | "[email protected], [email protected]" | |
| sms | string | The phone number/s the alert may be sent to in Australian 04xxxxxxxx format or international E.123 format Multiple numbers are separated by a comma | no defaults to none | "0444 444 444, 0433 333 333" |
| push_notifications | boolean | Whether to send push notification to a phone/s logged into the app | yes | 1 or 0 |
| alert_type | string | The type of the alert. Details for this section are below | yes | journey |
| alert_criteria | string | The criteria used for the inputted alert type Details for this section are below | yes can be an empty string | journeyAfterParked30 |
| status | Bool | Whether the alert is active or not | yes | 1 or 0 |
| ac_notes | String | Alert criteria notes. Specifically for maintenance alerts (Maint*) only. A note which will be included in the email when this alert is raised. | no | Tire change and wheel alignment |
Alert types and their event criteria
There are various alert types available, the criteria variable is used to extend the alert.
| alert_type | Monitoring | alert_criteria type | alert_criteria range | Criteria description |
|---|---|---|---|---|
| powerBelow | Vehicle's voltage | float | 0-32.0 | The voltage threshold (Volts) |
| accOffToOn | The vehicle turned on | empty | - | - |
| autoGeofence | Movement while the vehicle is off | empty | - | - |
| motionSensor | Motion sensor triggered while the engine is off | empty | - | - |
| inputs | Device input changes | string | <input name>_<new state> input1_high input2_high input1_low input2_low | the input to monitor and the new stage input1_high creates an alert for when input1 switches to high |
| harsh_acceleration | Vehicle accelerating rapidly | string | <vehicle_type>_<threshold in 0.01G’s> Vehicle types are: Passenger: 1 Van or truck: 2 Heavy vehicle: 3 Custom: 4 The threshold ranges from 0.25 to 3.0 G | The vehicle type and the minimal detected acceleration in 0.01G's 1_100 creates an alert for a passenger vehicle for an acceleration of 1 or more G’s |
| harsh_braking | Vehicle braking abruptly | string | <vehicle_type>_<threshold in 0.01G’s> Vehicle types are: passenger: 1 Van or truck: 2 Heavy vehicle: 3 Custom: 4 The threshold ranges from 0.25 to 3.0 G | The vehicle type and the minimal detected acceleration in 0.01G's. 3_100 would create an alert for a Heavy vehicle for a braking event of 1 or more G’s. |
| harsh_cornering | Vehicle turning rapidly | string | <vehicle_type>_<threshold in 0.01G’s> Vehicle types are: passenger: 1 Van or truck: 2 Heavy vehicle: 3 Custom: 4 The threshold ranges from 0.25 to 3.0 G | The vehicle type and the minimal detected acceleration in 0.01G's 1_100 creates an alert for a passenger vehicle for a turning event that creates a force of 1 or more G’s |
| journey | Device trips | string | journeyDuration3 journeyDuration2 journeyAfterParked30 journey6to6 journey23to6 journey00to11 journeyWeekend journeySaturday journeySunday journeyWeekday journeyAnytime | Moving for more than 3 hours Moving for more than 2 hours Moving after being stationary for more than 30 minutes Moving between 6 pm and 6 am Moving between 11 pm and 6 am Moving between Midnight and 11 am Moving on the weekend Moving on Saturday Moving on Sunday Moving on a weekday Vehicle detected moving |
| speeding | The device records a data point with a speed greater than the given one | String | speeding<speed in km/h> speeding108 | A speed exceeding the given speed A speed exceeding 108km/h |
| speeding_sustained | The device records 3 data points with a speed greater than the given one | String | speeding<speed in km/h> speeding108 | A sustained speed exceeding the given speed A sustained speed exceeding 108km/h |
| zoneExit | Vehicle exiting a zone | String | * Comma separated uniqueIDs 23hcdj2ns, 4247ahsa | A zone exit alert will be created for all zones. A zone exit alert will be created for the zones 23hcdj2ns, 4247ahsa. |
| zoneEnter | Vehicle entering a zone | String | * Comma separated uniqueIDs 23hcdj2ns, 4247ahsa | A zone enter alert will be created for all zones. A zone enter alert will be created for zones 23hcdj2ns, 4247ahsa. |
| MaintOdometer | Odometer based maintenance | int | <odometer in km> 120 000 | A maintenance alert will be triggered once the device's odometer exceeds 120 000km. An “approaching maintenance alert” will also be triggered, when the odometer is within 1000km of the target. |
| MaintEngineHourmeter | Alert based on engine run time | int | <engine runtime in seconds> 360 000 | An alert will be triggered as the engine hour-meter approaches and exceeds 360 000 seconds (100 hours). An “approaching maintenance alert” will also be triggered, when the engine hour-meter is within 10 hours of the target. |
| MaintTravelDate | A future date for maintenance | String | <YYYY-MM-DD> 2022-06-30 | An alert will be triggered once the date in the local timezone of the device exceeds 2022-06-30. An “approaching maintenance alert” will also be triggered, when the date is within 7 days of the target. |
Returned Data
Action-Delete
Delete an existing alert.
module=alerts&action=delete
Required data
To delete an Alert, add the alert's unique ID into the data variable unique_id. For example, data[unique_id]=23hhfHD92hsjKA
Example request
https://app.trackmyride.com.au/v2/php/api.php?api_key=GF83FDSa72hds82jfFD82js123j3284mw8223&user_key=gtr873ns2eDSf111&module=alerts&action=delete&data[unique_id]=DcSRjK2xWlCF
Returned Data
Action-Criterias
Return all configured alerts linked to the account.
module=alerts&action=criterias
Example request
https://app.trackmyride.com.au/v2/php/api.php?api_key=GF83FDSa72hds82jfFD82js123j3284mw8223&user_key=gtr873ns2eDSf111&module=alerts&action=criterias&json=1
Returned Data
| Name | Description | Example |
|---|---|---|
| If XML: data contained inside <data> | Array of objects | { unique_id: 1544759850 vehicle_id: * alert: zoneExit, 34874hjdfas contact: "{email: [email protected], sms: 0432 123 123}" push_notifications:1 trigger_count: 21 creation_limit: 15 dayparts_ignore: "[{day: 0, hour: 10}]" zones_ignore: 2hs8abd zones_limit: status:1 ac_notes: A note for the alert } |
Data included in returned data
For each row, the following data is included
| Name | Description |
|---|---|
| unique_id | The alert's unique id |
| vehicle_id | Vehicle/s the alert is for. * is used for all vehicles |
| alert | Alert type and criteria, concatenated |
| contact | Contacts are to be notified, as a string conversion of a JSON object |
| push_notifications | Whether the alert will trigger push notifications |
| trigger_count | Number of times the alert has been raised |
| creation_limit | How frequently the alert can be triggered, in minutes |
| dayparts_ignore | Hours in a day to suppress the alert [{ day:0, hour:10 }] -> the alert will not be raised from Sunday from 10:00 am to 10:59 am |
| zones_ignore | Zones that the alert will not be raised in. Given as a comma-separated list of zone unique ids |
| zones_limit | Zones the vehicle must be in for the alert to be raised. Given as a comma-separated list of zone unique ids |
| status | Whether the alert is enabled or disabled (1 or 0) |
| ac_notes | Notes to accompany the alert, specifically applicable for maintenance alerts only. |