GPS Data Web Service API

Home: Introduction

Push Notifications

It is possible to setup push notifications to be alerted as soon as certain events occur. This page explains the format and transport of these push messages, as well as how to use the web service to set up notifications.

Notification Data Formats

When you set up a notification, event data will be "pushed" to you immediately when our server receives the data from your GPS tracker. Depending on the type of target, this will happen via email, HTTP (POST) or SMS (text messaging).

With the exception of a text message, a list of key/value pairs are programmatically sent which indicate the type of event, the GPS tracker that had the event, and other data. The following values are always available:

imei
15-digit IMEI of your tracking device
name
The human-readable name of your device
event_id
This is the property from the Event Type object. The list of all Event Types is also available from the webservice (it won't change very often).
unix_ts
UNIX timestamp that the event occurred (from GPS tracker)
iso_8601
Format of the time according to ISO 8601, more specifically: YYYY-MM-DD'T'hh:mm:ss'Z' ('T' and 'Z' means those characters appear literally, but without the quote marks). This is always in UTC.
zone_name
The name of the Zone, as set in zone.name. Zone Events only
cross_type
This is either entry or exit. Zone Events only
latitude
Latitude (in decimal format) where event occurred, only if available
longitude
Longitude (in decimal format) where event occurred, only if available
address
For a few events (Panic Button, Battery Disconnected), the address is pre-geocoded and sent in this parameter as a convenience, only if available

HTTP POST

When the data is sent via HTTP POST, the key/value pairs are sent using the ubiquitous URL encoding (below, [...] would be substituted for real values): 

POST /example-event-script HTTP/1.0
Host: example.com
Content-Type: application/x-www-form-urlencoded
Content-Length: [...]

imei=[...]&name=[...]&event_id=[...]&unix_ts=[...]&iso_8601=[...]

The encoding is always UTF-8.

Email

Sending events via email is mostly for humans to read, so the first part of the message (and the subject) of the email is a very short human-readable message using the GPS tracker's name, Zone name, etc. The key/value pair data is appended to the email, however, should it need to be programmatically processed. If there are line breaks in the data (e.g., address data), the second line will begin with a tab (ASCII:0x09) character, as in the example below. 

... [human-readable part of email] ...

-----BEGIN EVENT DATA-----
imei:[...]
name:[...]
event_id:[...]
unix_ts:[...]
iso_8601:[...]
address:[first line]
	[second line]
latitude:[...]
longitude:[...]
-----END EVENT DATA-----

Setting up Notifications

Setting up Event Notifications and Zone Notifications can be a confusing affair. Here are a few tips that might help.

Limit the Scope

The first thing to do is decide, probably via user input, which notifications ought to be edited. You can follow the URLs from various resources to locate just the part of the notifications that you want to edit.

For example, say you have fetched a Tracker data object. One of its properties is event_notifications_url. You can GET that data object to access Event Notifications just for that Tracker.

Assuming you only want to edit which Target gets the notified for this tracker when the Ignition Off event occurs, you can follow the narrow_url link for that event type (find it in event_types list of the data object you just retrieved, as documented under Event Notifications).

Edit the notifications

What you have when you follow that URL is a list of notifications which only pertain to both the Tracker and the Ignition Off Event. You can then edit the notifications property: add items, remove items, or change some of the properties of the Notification Specification, and PUT the edited data back to the URL you just retrieved.

The Scope is Important!

The scope of your edits always remains true to the URL you used to fetch the items. So if you have limited the scope to the notifications active for a particular Tracker object, everything in notifications is assumed to be for that Tracker when you PUT it back, and the tracker_url property of the Notification Specification is ignored.

Example Workflow

Let's say a user wants to edit the Zone Notifications for a particular tracker. The user wants to setup event sending for all Targets and all Zones, on either entry or exit, for that tracker.

  1. Get the gateway, always the first step
  2. Follow gateway.trackers_url
  3. In the trackers.trackers list, each tracker has property event_notifications_url, so GET the link for the appropriate tracker.
  4. That URL limits the scope to notification only active for that tracker. Now, we want to set the property event_notifications.notifications to have every combination of Targets and Zones. There may already be some notifications set up, but we will just overwrite it.
  5. Create every possible combination of targets and event_types. Recall that for an Event Notification Specification, we need tracker_url, target_url and event_type_url. All other values have defaults. However, the tracker_url is already "set" in the URL, since we followed the link for just the tracker's notifications, so we don't need that, either.
  6. Once the notifications have been generated, overwrite the settings using HTTP PUT at the same URL.

Here's a bit of pseudocode indicating how this task might be accomplished: 

// create a service object to manage communication
service = gink_service("http://mygink.com/rest/v2/", username, password)

// find the event_notifications we want to edit
gateway = service.get("gateway")
trackers = service.get( gateway.trackers_url )

// assume you have some way to pick the tracker you want
tracker = find_tracker( trackers )
event_notifications = service.get( tracker.event_notifications_url )

// reset the event_notifications.notifications list
event_notifications.notifications = []

// iterate over all available targets & event types
// the are also available in the event_notifications object
for target in event_notifications.targets:
  for event_type in event_notifications.event_types:
    event_notifications.notifications.push({
        event_type_url: event_type.event_type_url,
        target_url: target.target_url
    })

// PUT the updated object back to the server
service.put( tracker.event_notifications_url, event_notifications )
Home: Introduction