GPS Data Web Service API

Data Objects

Please see Naming Conventions for a quick introduction to how data objects are structured.

The following data objects are exposed via the web service:

Gateway (Entry Point)

This object is the main entry point into the GPS data web service. It provides links to other parts of the service, and is always accessible. See Accessing the Service.

token_url
The URL at which you can authenticate via time-limited token
token_valid
If token authentication has been presented, indicates the validity of the token, otherwise not set
auth_basic_url
A URL which, if not currently using Basic Authentication, will trigger the process of HTTP Basic Authentication. Otherwise, if the client uses Basic Authentication and is correctly authenticated, it will redirect to the gateway.
auth_basic_valid
boolean: indicates validity of HTTP Basic Authentication credentials
auth_digest_url
A URL which, if not currently using Digest Authentication, will trigger the process of HTTP Digest Authentication. Otherwise, if the client uses Digest Authentication and is correctly authenticated, it will redirect to the gateway.
auth_digest_valid
boolean: indicates validity of HTTP Digest Authentication credentials
account_url
Link to basic information about your account
trackers_url
Link to the list of trackers you have access to via the web service
live_url
Link to current status of your trackers
zones_url
A link to all previously created zones. POST creates a new zone.
targets_url
A link to previously defined notification targets. POST creates a new notification target.
timezone
String representing the currently used timezone. This is only used when determining when end-of-day occurs.
timezones_url
Link to list of time zones, and links to select them
event_types_url
A link to a list of currently available Event Types. These can be used in configuration of event notifications.
registration_url
If you request the gateway without authenticating, you can POST a new account object to register

Account

Available via gateway.account_url. Can also be POSTed to the gateway.registration_url to create an account.

Contains account information, and links to your balance history. Many of the properties on this object are editable, and you can change them to let us know if some of your data has changed.

username
Your unique login username
password
NULL for GET requests, required to change password or username via PUT
new_password
NULL for GET requests, required to change password via PUT
company
Your company name
contact
The contact person for us at your company
address
The physical address of your company
phone
Telephone number of company
fax
Fax number of company
email
Contact email address. It is a very good idea to keep this current. Required for new registrations.
balance_m
The available balance on your account which may be used to send messages (or other paid functionality which we may make available in the future). Currently this is reduced only when we send an alert SMS that you have pre-configured.
balance_history_url
Link to the history of any charges we have run against the balance. See Balance History.
gateway_url
Link back to the gateway resource

If you are creating a new account via the gateway.registration_url, you'll need to add a tracker immediately to link to the account. This property never exists on GET requests, and is only for new registrations. You may also need to specify the partner ID for some custom functionality (only if already discussed with us). This ID will also not be present int GET requests.

imei
The IMEI of your tracker (must have never been registered)
partner
Only for certain partner functionality

Balance History

Available via account.balance_history_url.

Provides a listing of charges and deposit history that have been run against your account for sending SMS alert messages.

account_url
Link back to the Account
balance_m
[string|null] The available balance on your account. This is null if a for-pay account has not been set up yet.
balance_history
List of charges and deposits that have affected the balance on your account.
ts
UNIX timestamp of entry
amount_m
Amount that was charged/deposited in Euro
new_balance_m
The new balance of the account after applying the deposit or charge
reason
One of "deposit", "url-charge" or "url-chargeback". A url-chargeback indicates a reversal of a url-charge, in which case we attempted to send a for-pay alert message, but the delivery failed.

GPS Trackers (List)

Retrieve via gateway.trackers_url.

Your GPS trackers are probably the assets most important to you. They have lots of links to get the historical data and other parts of the service.

gateway_url
Link back to the gateway resource
live_url
Link to the Live Tracking URL for polling
trackers
A list of tracker objects

GPS Tracker

Available from trackers.trackers (array).

imei
International Mobile Entity Identification Number, the identification number that is hardcoded into the tracker's hardware
name
A convenience name for the tracker
start_ts
UNIX timestamp: this is the timestamp after which you have access to the tracker. Usually you have access for the entire life of the tracker, but in some situations we may create a limited access to the tracker (possible at your request).
end_ts
UNIX timestamp: after this point in time, you will no longer have access to the trackers's data via the web service. Because the web service access is purchased for a pre-arranged amount of time, you can think of this as an expiration date (which you can renew).
data_retention
The number of days in the past for which tracker data will be saved and accessible via the web service. This is currently usually 93 days, but it could be more or less depending on the package you have purchased from us.
model
The hardware model of the tracker
tracker_url
Link to the tracker URL where data (e.g. name) can be changed via HTTP PUT
dates_url
Link to a list of dates for which tracker data is available
event_notifications_url
Link to the Event Notifications just for this tracker
zone_notifications_url
Link to the Zone Notifications just for this tracker
din_map
List of names and Digital Input Event Profiles for a tracker's digital inputs.
din_idx
Digital Input index
din_name
Name of Digital Input
din_event_url
Digital Input Event Profile URL

Live Tracking

The Live Tracking object is intended to be available for continuous polling in such a manner that the current status of your GPS Trackers can be continuously updated.

gateway_url
Link to the Gateway
live_url
The next URL to request (via GET) to retrieve only those updates that have come in since calling this data object
updates
A list of current status updates:
tracker_url
Link to the GPS tracker that the update applies to
pos_ts
UNIX timestamp: time that positional data was updated
latitude
Latitude of tracker logged at pos_ts
longitude
Longitude of tracker logged at pos_ts
altitude
Altitude of tracker logged at pos_ts
speed
Speed of tracker (km/h) logged at pos_ts
angle
Angle (bearing) of tracker logged at pos_ts 0=North, 90=East, etc
satellites
Number of available satellites logged at pos_ts
battery
Battery level in percent, 0-100, logged at pos_ts
power_connected
0: external power disconnected; 1: external power is connected; null: external power not available
ignition_ts
UNIX timestamp: ignition signal updated
ignition_on
0: ignition is off; 1: ignition is on; null: ignition signal not available
conn_ts
UNIX timestamp: GPS tracker connection status updated
channel
The connection channel at which the tracker is connected (e.g. 'tcp://127.0.0.1:80')
digital_inputs
A list of simplified Log Entries. Each entry contains only the properties din_idx, din_val and ts

Tracker Dates

Available from tracker.dates_url. The list of dates for which GPS tracker data is available is another very important resource. From a single date you can get the positions for the entire day, the tour summary, events and external tracker input data.

gateway_url
Link back to the gateway
trackers_url
Link back to all available trackers
timezone
The time zone that was used to calculate the division of dates
timezones_url
Link to the list of timezones (for setting timezone)
tracker_url
Link to the tracker object
dates
List of available dates and links to further data:
date
The date in format YYYY-MM-DD for which data is available
positions_url
Link to all positions for the given day
tours_url
Link to the calculated tours for the day
events_url
Link to events reported from the device for the day
tracklog_url
Link to a combined view of positions, events and input data (digital & analog inputs)
digital_inputs_url
Link to the digital input data for the day
analog_input_url
Link to analog input data for the day
binary_messages_url
Link to binary message data for the day

GPS Tracker Log

The GPS positional and event history is an important piece of any tracking system. The webservice provides a few different ways to query this data, and you can simply choose the best one based on your application needs. Most importantly, all of the available logged data is well-linked to the other parts of the logged data, making it easy to jump from one view to the other.

The different parts of the GPS tracker log can be accessed via the GPS Tracker Dates resource, and following the links from there. The data objects returned by each of the URLs from the GPS Tracker Dates are all very similar. However, in the log parameter that is returned (which is a list), they differ regarding what data is reported. For consistency, however, the property names are unique and always refer to the same type of data.

gateway_url
Link to get back to the main entry point of the web service
timezone
The time zone that was used in calculating any end-of-day times
timezones_url
Link to the selection of Time Zones to change the end-of-day calculations
dates_url
Link to get back to the list of all available dates from the GPS tracker
related
This is an object that links to related information for the GPS tracker. It contains links to all the other parts of the log for the same period of time. One of these will always be missing, because it would only link to the resource you are already viewing.
positions_url
Links to GPS positions part of the tracker log
tours_url
Links to the server-calculated tours
events_url
Link to events part of the tracker log
digital_inputs_url
Link to the digital input data
analog_input_url
Link to analog input data
tracklog_url
Link to the combined view of positions, events and input data
binary_messages_url
Link to binary message data
log
Missing if the resource is from tours_url. This list contains the logged data from the request. It is full of Log Entries (possibly empty, if there is no data).
tours
Missing unless the resource is from tours_url. A list of calculated tour entries.
filters
Available only on a tour resource, this is a list of tour filters that were used to calculate the tour

GPS Tracker Log Entry

A GPS tracker may be able to log lots of different kinds of data. A log entry is always a subset of this data.

ts
UNIX timestamp of the log entry
latitude
GPS Latitude recorded at time of entry
longitude
GPS Longitude recorded at time of entry
hdop
Horizontal Dilution of Precision
pdop
Positional Dilution of Precision
speed
Speed in kilometers per hour at time of entry
angle
Angle, or bearing of tracker at time of entry
meters
The distance (in meters) from this logged entry and the one directly previous to in chronologically
event_id
The Event Type that occurred at the time of entry (most often, this is null)
event
For convenience, an English description of the event matching to event_id
event_extra
Some events have a smidgeon of extra data attached to them. That can be found here.
din_idx
The index of a digital input pin, always appears with din_val
din_val
The value, zero or one, of the corresponding digital input pin. Always appears with din_idx.
ain_idx
The index of an analog input pin, always appears with ain_val
ain_val
The value, in millivolts, of the corresponding analog input pin. Always appears with ain_idx.
binary_message
A Base64 encoded binary message from the GPS Tracker (RFC 2045, sec. 6.8 alphabet)

GPS Tracker Tour Entry

An entry in dates.tour_url.tours. A tour entry is calculated based on a combination of filter algorithms, and consists of a start point, end point, and other metadata for the tour. It also contains links to retrieve more detailed log entries.

start
A log entry indicating the start of the tour
end
A log entry indicating the end of the tour
time
The number of seconds of the tour from start to end
meters
The total distance, in meters, covered by the tour. Note that this can differ from odometer distance due to GPS inaccuracy and a difference in the way the distance is measured.
count
The number of GPS waypoints in the tour
positions_url
Link to the positional part of the GPS tracker log for just this tour
tracklog_url
Link to the combined view of positions, events and input data

Tour Filters

In the best case, your GPS tracker is installed in a vehicle with ignition data being reported to our servers. If not, we try our best to determine tours based on speed, distance, or time between data points. Either way, the calculation of tours passes through a series of what we call "tour filters", and the choice of filters that manage tour determination is left open to you.

Currently, the tour filters are selected automatically. We will look to open up the API further very soon in the future to make the creation of tour filters very, very easy.

split_ignition
The most ideal way to split up tours, this method divides the tours based on ignition signals reported to our servers. It has no arguments.
split_idle
A less than ideal way to split tours, this method starts a new tour when too many seconds have passed between reported positions. It takes as an argument the number of seconds which may safely pass before a new tour will be started on the next point.
merge_breaks
If a tour filter has caused too many tours to be created, this filter can merge them together again. This is the counterpart to split_idle, and takes as its argument the number of seconds of pause that must pass to allow tours to stay separated. If the seconds between two tours is less than this number, two tours will be merged together.
min_time
You may want to completely discard tours that are very short. This filter will do that, and takes as an argument the number of seconds that a tour must span before being discarded.
min_count
You may want to discard tours that, for whatever reason, have too few points in them. This filter's argument is the number of points a tour must have to remain in the list of tours.

Targets (List)

Available from gateway.targets_url and account.targets_url. This is a list of endpoints that can be notified on the occurrence of an event or zone crossing. See Target for types of notifications.

gateway_url
Link back to the gateway object
trackers_url
Link to the trackers list
targets
List of Target objects

Target

A Target is an endpoint for event notifications. These are used to configure immediate (push) sending of alerts for events or zone crossings. You may configure SMS numbers, email addresses, HTTP URLs (sent via HTTP POST), or a server-side internal FIFO (for polling).

ident
The string that identifies the endpoint of notification. This can be:
name
A convenience name used to identify the notification endpoint
amount_m
The amount that your account is charged whenever a notification is sent to this URL. This is currently non-zero only if the endpoint is a phone number.
target_url
Link to the single target object (e.g., where you can PUT properties to update the endpoint URL or the name)
zone_notifications_url
Link to the Zone Notifications configured for the Target
event_notifications_url
Link to the Event Notifications configured for the Target

FIFO Target

A FIFO is created in the same way as a normal target, but the special string "fifo:" must be given for the property target.ident. When accessing a target object singly via its target_url, the property fifo_url is also available. It is not available when accessing the complete list of all targets.

NOTE: unlike most requests for user-specific data, accessing the FIFO does not perform authentication. This is intentional, as the FIFO is intended for repeated heavy polling. Consequently, the properties below should be considered as sensitive data.

fifo_url
The URL that can be accessed via GET to see the current contents of the FIFO.
ident
This property is NOT editable for FIFO targets. A target can be checked if it's a FIFO when it matches the regular expression /^fifo:([a-zA-Z0-9]{40})?$/

FIFO

A FIFO (first in, first out) is an internal area to save event notification within the web service. It exists on our server, and is intended to be polled, processed and cleared from within an application. It is intended for applications that need to reliably deal with notifications, but which are restricted to pulling data rather than receiving pushed data. See FIFO Target for instructions to create a FIFO.

gateway_url
URL back to the Gateway
targets_url
Link back to the Targets List
items
List of notifications currently in the FIFO.
data
Hash of key/value pairs. See Push Notifications for detailed information about the format.
logged_ts
UNIX timestamp: time the item was pushed into the FIFO.
delete_url
URL, called via HTTP DELETE, to remove just this item from the FIFO.
clear_url
URL, called via HTTP DELETE, to remove all the items just retrieved from the FIFO. Any items which arrive after this GET request, but before the DELETE request, will still be preserved. In other words, if you've processed all the items to your satisfaction, you can safely call DELETE (and it's idempotent). This property is only present when there are items retrieved.
next_url
URL, called via HTTP GET, to retrieve items that have arrived in the FIFO since this check. This will not cause the items to be deleted.

Time Zones

Available from gateway.timezones_url, and some others.

Any object that has timezones_url is a link to this resource. The timezones object has only one member, a list of timezones and links to change the setting. You can set the timezone yourself by setting the _tz parameter in the URL, or use this list.

timezones
List of names and links to set the time zone
name
Human-readable name of the timezone
set_url
Link to take you back to the resource you were at before, but with the new time zone set

Digital Input Event Profiles (List)

Available from gateway.din_events_url.

It is possible to setup a tracker's Digital Inputs such that an Event is generated whenever a value is sent via the Digital Input pin.

gateway_url
Link back to the Gateway
din_events
List of available Digital Input Event Profiles

Digital Input Event Profile

Available from din_events.din_events (array).

din_event_url
URL reference for this Profile
on_event_url
Event Type generated when "on" value is sent
off_event_url
Event Type generated when "off" value is sent

Event Types (List)

Available from gateway.event_types_url.

gateway_url
A link back to the Gateway resource
event_types
A list of available Event Type objects

Event Type

event_id
Unique integer for this type of event. May be useful in linking external applications.
event_type_url
Link to only this type of event
description
Short description, in English, of the type of event
event_notifications_url
Link to configured Event Notifications corresponding to this type of event

Zones (List)

Available from gateway.zones_url.

gateway_url
Link back to the gateway
zones
List of Zone objects

Zone

Available from zones.zones.

name
A human-readable name that can be used to refer to the zone in your application when displaying it to the user
zone_url
Link to the individual zone, e.g. for editing via HTTP PUT
zone_notifications_url
Link to the Zone Notifications list which is applicable only to this zone
fence
List of points which define the polygon on the Earth:
latitude
Surprisingly, this is the point's latitude
longitude
Even more surprisingly, this is the point's longitude

Notifications List (Base)

These properties are common to Zone Notifications and Event Notifications. A Notifications List is a collection of configurations that determine:

Please check out Push Notifications for an explanation.

notifications
This is a list of all configured notifications for the parameters given. Based on the type of Notifications List, every item is a Zone Notification Specification or an Event Notification Specification.
trackers
A list of simplified GPS Tracker objects. Each GPS Tracker in this list has an additional property:
narrow_url
Link to narrow the current list of notifications to only those that are active to this GPS tracker
all_trackers_url
If the current notifications are narrowed to those configured for a single GPS tracker, this URL links to the same notifications, but for all GPS trackers
targets
A list of simplified Target objects. Each Target object has an additional property:
narrow_url
Link to narrow the current list of notifications to only those active for this target
all_targets_url
If you are viewing notifications narrowed to a specific target, this URL leads to the view without that filter

Zone Notifications

Available from zone.zone_notifications_url.

This object adds a property to the general Notifications List that determines which Zone the notification is valid for. The objects in the property notifications are instances of a Zone Notification Specification. Be sure to read Push Notifications.

zones
A list of simplified Zone objects. An important property is available on each of the objects in the list:
narrow_url
Link to narrow notifications to only those that pertain to this Zone
all_zones_url
If the notifications are narrowed to only those for a single Zone, links to the same Zone Notifications, but without that filter

Event Notifications

Available from tracker.event_notifications_url and event_type.event_notifications_url.

This object adds a property to the general Notifications List that determine which Event Type the notification is valid for. The objects in the property notifications are instances of a Event Notification Specification. Be sure to read Push Notifications.

event_types
A list of available Event Type objects. Each Event Type object has an additional property:
narrow_url
Link to narrow the notifications to only those of this Event Type
all_event_types_url
If the notifications are narrowed to those of a single Event Type (e.g., via narrow_url, links to the same Event Notifications, but without that filter

Notification Specification (Base)

These properties are common to Event Notification Specifications and Zone Notification Specifications.

tracker_url
The tracker.url property for which the notification is configured
target_url
The target.url property for which the notification is active
active_wd
A mask of weekdays for which the notification is active
default: 254 (all days)
start_t
The time of day after which the notification will become active. Zone crossings before this time will not generate zone-crossing events
default: "00:00:00"
end_t
The time of day after which the notification will become inactive. Zone crossings after this time will not generate zone-crossing events
default: "24:00:00"
timezone
The time zone which should be used to compare the start_t and end_t parameters against
default: current timezone

Event Notification Specification

Available as an item in the list from event_notifications.notifications.

Additionally to the base Notification Specification, the Event Notification Specification identifies for which Event Type the notification is active. It has all properties of a Notification Specification, plus those below.

event_type_url
The event_type.event_type_url property for which the notification is active

Zone Notification Specification

Available as an item in the list from zone_notifications.notifications.

Additionally to the base Notification Specification, the Zone Notification Specification identifies for which Zone the notification is active, and whether the notification should occur on zone entry, exit, or both. It has all properties of a Notification Specification, plus those below.

zone_url
The zone.zone_url property for which the notification is active
cross_type
Via this parameter you can configure whether a notification is generated when the GPS tracker moves into the zone (cross_type=1), out of the zone (cross_type=2), both (cross_type=3), or neither (cross_type=0). Setting this to 0 has the effect of making the configured notification temporarily inactive, while not deleting it completely.