GPS Data Web Service

Introduction

NOTE: this version of the gink web service is deprecated. Please consult the documentation available for version 2 of the service.

Your gink-Box sends its GPS and event data to the server at mygink.com. The GPS and event data from the gink-Box are stored up to a maximum of 30 days. You should use the web service to download and save any data that you want to store for longer than this.

The following data can be retrieved via this REST web service:

Data is available via HTTP GET requests, which must include the application key as authentication (see Authentication).

NOTE: Consumers of this web service must take possible future changes into account:

Sample Application

There is a sample application available, which can show the devices available for a given access key, lookup total distances travelled, and retrieve position history in different formats. The source code may be freely copied & modified. Sample Application.

Data Formats

Data is availble in the following formats:

JSON (JavaScript Object Notation)
Each object is a JSON object, multiple objects are represented as a JSON array. See http://json.org/ for more details.
CSV (Comma-Separated Values)
Each object is a row, properties are separated by commas. Each string property is surrounded by double-quotes, numbers are not. The names of the properties are the first row. NOTE: if the request results in no data, there will also be no header.
XML
Each object is a node. Object properties are child nodes which contain the property value. Multiple objects are placed inside the root node.
KML
Keyhole Markup Language. This data format is only available for the devices.kml (current positions) and positions.kml (historical positions). The output is in a format that could be opened with Google Earth.
HTML
An HTML table of the results, useful to look at in your browser directly for demonstration purposes. The HTML should not be used for programmatic access, but only as a tool to quickly look at data in the browser. The HTML code returned is subject to change.

The desired data format can be specified using an extension on the URL.

http://mygink.com/rest/devices.xml
http://mygink.com/rest/devices.json
http://mygink.com/rest/devices.csv
http://mygink.com/rest/devices.kml
http://mygink.com/rest/devices.html

Time Formats

All response data that represents a time is in format "YYYY-MM-DD hh:mm:ss" (UTC). All response data representing a date is in format "YYYY-MM-DD". This is the officially supported input format (we try to be forgiving), and always the output format.

All times returned are given according to UTC time zone. Any input times are also interpreted as UTC times.
There is often a UNIX timestamp available in addition to the normal format "YYYY-MM-DD hh:mm:ss". This number is the number of seconds since Jan. 01, 1970 UTC. Many programming languages use this standard when dealing with dates & times. This parameter will be named "unix_ts" if available.
top

Authentication

In the following examples, the access key provided is 'example'.

Authentication via custom HTTP header

A custom HTTP header, “X-Bornemann-Auth”, can be used to provide the access key.

GET /rest/devices.xml HTTP/1.0
Host: mygink.com
X-Bornemann-Auth: example

Authentication via GET parameter

In addition to other parameters, the parameter '_key' can be provided to authenticate the request. This is the access key provided.

GET /rest/devices.json?_key=example
Host: mygink.com
top

Querying available devices / current device data

It is possible to get the most current positional information for all devices registered with your access key.

URL: http://mygink.com/rest/devices
GET: gets all devices available (for the access key)
PARAMETERS: none
RESPONSE: array of device objects
imei
the imei of the device
timestamp
time of last known position
unix_ts
UNIX timestamp of last position
latitude
last position latitude
longitude
last position longitude
name
alias for the device
NOTE: parameters timestamp, unix_ts, latitude, longitude and name can all possibly be null if there is no data available for the device (or it has never been named).
Example: http://mygink.com/rest/devices.html?_key=example
top

Querying total distance traveled

Total Daily Distance

Retrieve a summary of a day's information for a gink-Box, either for a single device (over multiple days), or a single day (of all devices).

URL: http://mygink.com/rest/distances
GET: gets one or more devices' daily total distance summary
PARAMETERS:
date
date for distance
imei
the 15-digit IMEI, to retrieve single device's data
RESPONSE: one or more objects with properties:
imei
IMEI of the device (if requesting for "date" only)
date
the date of the data (if requesting for "imei" only)
unix_ts
the UNIX timestamp of the start of the day
distance
distance traveled (km)
points
the number of GPS positions reported
start
time of the first GPS position for the day (hh:mm:ss)
unix_ts_start
the UNIX timestamp for "start"
end
time of the last GPS position for the day (hh:mm:ss)
unix_ts_end
UNIX timestamp for "end"
positions_url
a URL that can be called to fetch the detailed positions for the corresponding day
events_url
a URL that can be called to fetch the device's events for the corresponding day
Examples:
The "distance" field uses a full stop '.' as a separator, rather than a comma.
NOTE: if only 'date' is given, an array of all available devices for that date is returned.
If only 'imei' is given, an array of all dates available for that device is returned.
If both 'date' and 'imei' are given, only a single object is returned.
top

Querying position history

You may query the position history for a single device, up to a period of 24 hours maximum. The data (latitude, longitude, timestamp, etc.) can be used to reconstruct the path traveled for the given time period. The time period can be specified as a single day, or with a start and end time.

Alternatively, to get recently logged positions for your devices, you can specify a time since which the server logged the position from the device, rather than the time at which the device itself logged the position.

Note: either date, logged_since (optionally with logged_until), or both 'start' and 'end' are required, with a maximum time span of 1 day.

Note: Using the logged_since and logged_until parameters return positions based on the time that the server received the data from the device. The start / end and date parameters return positions based on the timestamp of the position data.

These are usually close to each other, but they are not the same thing, and in some cases (e.g. GSM connection unavailable), there may be quite a difference between the time at which the GPS device logged a position, and the time at which it was able to send its report to the server. The time that the server logged the position is not returned with the position data.

URL: http://mygink.com/rest/positions
GET: position history, for a single device, up to 24 hour period
PARAMETERS:
logged_since
retrieve positions that have been reported since this time. imei is optional when this is given. In that case, the recently logged positions for all your devices will be returned. The imei will then be added to the available data items, so you can distinguish which data points have come from which devices. Because this can potentially be a large amount of data, the maximum total time span for logged_since and logged_until is one hour if no imei given, or one day if limited to a single device via imei.
logged_until
retrieve only positions that have been reported before this time. See note about regarding optional imei parameter when using logged_since.
imei
15-digit IMEI of the device
date
date of the position history to retrieve
start
earliest time for a position
end
latest time for a position
RESPONSE: array of objects representing points:
timestamp
time of the position (UTC)
unix_ts
the UNIX timestamp of the position
latitude
latitude, in decimal format
longitude
longitude, in decimal format
altitude
altitude in meters, decimal format
angle
0-360, the angle of travel at this point
speed
speed (km/h) of vehicle at this point
meters
distance in meters to the previous point
Examples:
top

Querying Events

Depending on your GPS device and its connection to the vehicle, there are a number of events that your GPS tracker will send to our server. These data from these events can be accessed via the REST interface in a similar manner.

The most notable event is turning the ignition on or off, which can be used to designate a single trip. Depending on your device, events such as harsh braking, speeding or geozone crossing may also be supported.

URL: http://mygink.com/rest/events
GET: list of events for up to a week
PARAMETERS:
imei
15-digit IMEI of GPS device (to retrieve for only one device)
start
start time span (YYYY-MM-DD hh:mm:ss)
end
end of time span (YYYY-MM-DD hh:mm:ss)
date
alternatively, you may specify a date
You must specify either start + end, or a date.
RESPONSE: array of event objects
imei
the device's 15-digit IMEI
timestamp
time of the event in format YYYY-MM-DD hh:mm:ss (UTC)
unix_ts
time of the event as a UNIX timestamp
event_id
each event type has a unique ID, see below for complete list
event
a human-readable description of the event type

Available Events

event_id event
1 Ignition On
2 Ignition Off
3 Power Connect
4 Power Disconnect
5 Vehicle Idle
6 Vehicle Moving
7 Device Battery Low
8 Device Battery Failure
9 Vehicle Battery Low
10 Vehicle Battery Failure
11 GPS Removed
12 GPS Attached
13 Trip Begin
14 Trip End
15 Button Pushed
16 Panic Button
17 Device Boot
18 Device Shutdown
19 Driver Key Shown
21 Ignition Prevented
22 Ignition Allowed
23 Driver Key Missing
25 Towing Started
26 Towing Stopped
27 Excessive Acceleration
28 Excessive Braking
29 Forceful Impact
30 Geozone Entered
31 Geozone Exited
33 Digital Input On
34 Digital Input Off
35 Analog Input
36 Private Journey Started
41 Harsh Cornering
Examples:
top

Limitations of the service

Time Zones

When aggregating data, the server uses the UTC time zone to gather data into a single day. For example, data before UTC midnight will fall into "yesterday" and data after UTC midnight will fall into "today". Currently this is relevant in querying total daily distance.

If you are in a time zone that is close to UTC, the difference probably does not matter if your vehicles are not driving within a few hours of midnight (UTC time). However, if your vehicles are active around UTC midnight, the distance data that you expect to be on a single day might be split into two days.

You can expect this limitation to be lifted soon.

Device Identifiers

Because most GPS tracking devices identify themselves via the modem's IMEI, we have chosen this as the unique identifier for the tracking devices. Most vehicle tracking software adds a convenience to identify the vehicle via the license plate or some other name. This limitation will also be lifted shortly, by allowing a call to the web service to change the device's name which will be returned when querying available devices.

Addresses

No support is currently provided for mapping GPS coordinates to addresses. Depending on your application, this might be something you add to the client machine, or include in the mapping software.

Event Notification

While it is useful to track event data in a log, it might be even more advantageous to allow real-time notifications on certain events (e.g., "Forceful Impact" or "Towing Started"). Currently this is not supported, but will likely be implemented in a future version of the service.