An Introduction to GAP and the API

The Global Alerting Platform (GAP) is a device independent hub for messaging devices providing location tracking, emergency alerting, message routing and storage.

GAP also acts as a gateway to terrestrial messaging systems including, but not limited to, GSM, SMS and email as well as social network platforms, such as Twitter and Facebook.

Whether your message is a position report, an emergency alert or a simple text message, our hub can transform and route the message to any destination. For example, if you are a single handed fisherman you can route a man-overboard alert directly to the search and rescue services or if you are hiking in the mountains, you can configure your account to automatically "tweet" your location to all your friends. In a lone worker scenario, you could send a message from your Iridium SBD based device to another user with a totally different device on another terrestrial or satellite network.

Emergency messages can be relayed to first responder centres or directly to SAR authorities, based on location and nationality. GAP is fully integrated with the GEOS International Emergency Response Coordination Centre (IERCC). Please note that extra charges may apply.

In a world of rapid technological innovation and ever changing standards, the ability to interoperate between messaging systems is an increasing problem. Being able to automatically translate from one message format to another without user intervention is a unique service provided by GAP. For example, it is possible to send a text message from your handheld device and have it delivered as an email and vice versa. Similarly, you can send an SMS message from a terrestrial phone and have that delivered as an Iridium SBD message.

Powered by Windows Azure®, Microsoft’s cloud computing technology, GAP has been designed from scratch to provide near limitless scalability, high availability and integrity. Distributed across a network of globally inter-connected datacentres, GAP provides a secure way to globally route messages between devices, corporate systems, search and rescue authorities and personal end points.

Access to the platform can be achieved through a number of mechanisms depending on the requirements. GAP provides a customisable web portal that allows consumers and business users to configure devices, route messages and plot locations and tracks. This documentation describes the REST API. This mechanism allows developers to integrate devices of their own or build their own applications for consuming device data.

Using the ‘compute on demand’ features of Windows Azure, GAP allows for dynamic changes in traffic load ensuring there is always sufficient compute power to cope with growth. Additional compute power can be provisioned at the 'press of a button'. The underlying software has been architected to be horizontally scalable, meaning it scales linearly with increased compute power.

One of the main advantages provided by the platform is robust availability based on extensive redundancy achieved with virtualization technology. GAP provides numerous levels of redundancy to provide maximum availability of customers data. Data is replicated to three separate nodes within the platform to minimize the impact of hardware failures. Customers can leverage the geographically distributed nature of the platform infrastructure by creating a multiple accounts to provide hot-failover capability. In such a scenario, customers may create custom roles to replicate and synchronize data between datacentres.

Confidentiality ensures that a customer's data is only accessible by authorized entities. GAP provides confidentiality via the following mechanisms:

  • Identity and Access Management - Ensures that only properly authenticated entities are allowed access.
  • Isolation – Beyond authenticating access to data, compute and storage elements are logically or physically separate.
  • Encryption - Used internally within the platform for protecting control channels and is provided optionally for customers who need rigorous data protection capabilities.

The platform has multiple levels of monitoring and integrity checking. Each compute node has a monitoring agent that monitors the health of the virtual machine (VM) node on which it runs. If the agent fails to respond, the platform reboots the VM. In case of hardware failure, the platform automatically creates a new hardware node and reprograms the network configuration to restore the service to full availability.

Concepts

The platform is multi-tenanted and hierachical, meaning that for any given account, the platform can be partitioned up into a logical tree structure to suit the client's needs. For example, the parent tenant can create one or more sub-tenants, each with their own security boundary. These may typically be a distribution chain for device resellers or organisational units within an enterprise.

Each tenant can have one or more devices associated with it. Each device is typically assigned to an end-user. A tenant can be configured to register multiple device types at the same time within the scope of the tenancy. A tenant administrator can also create sub-tenants and create users within that sub-tenant. Users within that sub-tentant cannot see other users or devices outside of the sub-tenant security boundary. The tenant adminstrator can also delegate administrator permissions to the sub-tentant to permit the sub-tenant to manage devices and users independently.

Message Processing

A device can send a message to GAP via various mechanisms. Depending on the device, this can be via a proprietary connection to a telecomms provider, SMTP, a Short Messaging Service (SMS) or via this REST API.

The semantics of the message are specific to the device type and are often proprietary. However, almost all messages share a set of common properties, including a geographical location, a text message, one or more recipients and a set of flags. GAP supports generic devices through an advanced protocol. This permits devices of any type to send messages containing virtually any parameters (for more information, please contact us). On reciept of a message, GAP decodes the message, stores it and passes it to a routing engine. The routing engine determines the recipients (if any) of the message from a configurable address book and then translates the format to suit the recipient device or devices, be it email, SMS or another proprietary device. The API client does not have to be concerned with how this is achieved, but merely calls the API and GAP takes care of the processing! The API exposes methods to retrieve the messages sent into GAP as well as methods to retrieve messages sent from GAP as a result of the inbound message. The inbound messages are referred to a "mobile orginiated (MO)" and outbound messages as "mobile terminated (MT)". MT messages are read-only as they are generate by GAP as a result of the message processing and routing.

Message Routing and the Address Book

In order to route a message from a device to a recipient, you need to set up one more address book rules. Address book rules are based on specific message type defined in the address book events and address book distribution list containing individual recipients. Each distribution list can contain multiple entries and each entry can be an email address, a mobile telephone number for SMS messages (if enabled for your account), or links to your Twitter or Facebook accounts. When a message is received from a device, the message is inspected to determine if the recipient is a valid email address. If it is, then the message is forwarded to the specified address. If not, the recipient specified in the message is compared to the distribution lists for the device. If a match is found, the message is sent to all the addresses in the distribution list. For example, if you create a distribution list called "Friends", and add one or more reciepients to that distribution list, then if you address your message to "Friends" your message will be routed to those recipients. Different type of message, defined by address book event, can be routed to different distribution list. For example emergency messages (Event id: Other-Emergency) can be routed to 'Emergencies' distribution list. You can add new distribution lists and address book entries via the portal or via the API.

Address Type Definition
mail:<emailaddress> Sends the message to the email address e.g. mail:bob@aol.com
<device type>:<imei> Sends a message to an Iridium Short Burst Data device e.g. shout:303412345678901.
tweet:<userid> Posts a message to the twitter account associated with the registered owner of the device. The "userid" is a GUID and can be found in the user object.
facebook:<userid> Posts a message to the Facebook account associated with the registered owner of the device. The "userid" is a GUID and can be found in the user object.
sms:<mobilenumber> Routes the message to a mobile phone number via SMS e.g. sms:+447720296325. Please note that extra charges may apply.
 
contact:<contactId>/<entryId> Sends the message to the address book contact. The "contactId" is a GUID and can be found in the AddressBookContact object. The "entryId" is a GUID and can be found in the AddressBookContactEntry object. This address format can be used only when creating Address Book List Entry.

Please note that creation of 'tweet' and 'facebook' address book types can only be achieved via the web portal in this release of the API.

Geofences

A geofence is a virtual perimeter around a geographic region. As your device reports its location, the platform monitors the reports and determines whether the device has crossed into or out of the geofence. When the geofence is crossed, you have the option to send a notification to one or more recipients.

There are 2 supported types of geofence: circular, where the fenced-in area is a circle, or polygon, where the fenced in area is defined by a line joining separate coordinates. Multiple geofences are supported per device at any one time.

Check In Schedules

Check-in schedules can be used to specify times when a device must check in. A device that hasn’t reported according to its schedule will be marked as overdue and a message will be sent to specified recipients. You can create a schedule based on “Selected Times” or “Intervals”. For selected times, you specify the times that a device must check in. For intervals, you specify the start and end time. In addition, the “Buffer Period” is the grace period either side of check in time before the Portal will send an overdue message.

Canned Messages

Canned Messages are preset messages which can be sent by the device. They are designed to save the user from having to type frequently used messages. Canned Messages are divided into 2 groups of 15. The first 15 are preset for you by the System Administrator. A normal user cannot edit these preset messages. The second set are user definable and can be edited at any time. Canned messages are most frequently used to minimise the amount of data that needs to be transmitted between the device and the platform. This is of particular relevance for high cost bearers.

Creating an account

Before you can use this API, you must have an account on GAP. Please contact your service provider for more information.

Things to know about the REST API

The API is entirely HTTP-based. Methods to retrieve data from the API require a GET request. Methods that submit, change, or destroy data require a POST. A DELETE request is also accepted for methods that destroy data. API Methods that require a particular HTTP method will return an error if you do not make your request with the correct verb. HTTP Response Codes are meaningful.

The API is a RESTful resource. The API attempts to conform to the design principles of Representational State Transfer (REST). Simply change the Accept header of a request to get results in the format of your choice e.g. Accept: application/json. You may also suffix the resource url with a media type identifier e.g. ?format=json. The documentation notes which formats are available for each method. The API presently supports the XML, JSON and JSONP data formats, with some methods only accepting a subset of these formats.

Rest API Limits

  • Clients may access a maximum of 1000 results from a single request
  • Requests for more than the limit will result in a reply with a status code of 200 and an result containing 1000 records in the format requested.
  • There are limits to how many calls and changes you can make in a day.
  • API usage is rate limited with additional fair use limits to protect GAP from abuse.

If you are starting with the API, please familiarize yourself with the API FAQ and know that it exists.

The GAP API provides built-in support for a subset of the Open Data Protocol (OData) query string parameters that a client can use to sort or filter the results.

Parameter Description Example
$filter Selects entries that match a Boolean expression. https://api.globalalerting.com/1234/devices?$filter=substringof('MyDevice',FriendlyName) eq true
https://api.globalalerting.com/1234/devices?$filter=EmergencyState eq 1
$orderby Orders the results by the specified property. https://api.globalalerting.com/1234/devices?$orderby=Name
$skip Skips the first n elements. https://api.globalalerting.com/1234/devices?$skip=2
$top Returns the first n elements in the list. If combined with $orderby, the list is sorted first, and the first n elements of the sorted list are returned (max 1000). https://api.globalalerting.com/1234/devices?$top=10

Some Further Examples:

1. Return MO messages filtering on sequence number and return json

  • https://api.globalalerting.com/tenantCode/devices/deviceId/momessages?$filter=SequenceNumber eq 1&format=json

2. Return MO messages filtering on start dates/end dates

  • https://api.globalalerting.com/tenantDode/devices/deviceId/momessages?$filter=SentFromDevice ge datetime'2014-05-16T01:05:00Z' and SentFromDevice le datetime'2014-05-30T10:04:00Z'

2. Return last 10 MO messages

  • https://api.globalalerting.com/tenantCode/devices/deviceId/momessages?$top=10

The SMS interface

In order to send a message to GAP via SMS, you must have a commercial agreement in place with us. Once in place, we will issue you with a telephone number to which the messages must be sent.

Messages can be sent via SMS to GAP using the following format. You can only send messages for devices registered on GAP. We use the incoming Calling Line Idendity to validate the message is from a known device.

Start Position End Position Length Field Usage
0 0 1 Emergency Flag 0: Not an Emergency
1: Emergency
2: Cancel Emergency
1 2 2 Message Type 00: Automatic Position Report
01: Manual Position Report
02: Response To Location Request
03: Switch On
04: System Test
05: Diagnostic Response
06: Device Identifier Response
07: Synchronise
08: Free Text
09: Geofence Crossed
10: Begin Monitoring
11: End Monitoring
12: Check In
13: Canned Message Send
14: Message Acknowledgement
15: Deregistration
16: Power Down
17: Waypoint
3 14 12 Timestamp YYMMDDHHMMSS in UTC
Example:
111231235959 = December 31, 2011 23:59:59
15 15 1 Latitude Symbol -/+
0: No GPS reading
16 17 2 Latitude Degrees 00 – 90
18 20 3 Latitude Decimal 000 – 999
21 21 1 Longitude Symbol -/+
0: No GPS reading
22 24 3 Longitude Degrees 000 – 180
25 27 3 Longitude Decimal 000 – 999
28 30 3 Speed 000 – 998: In km/h
999: No reading
31 31 1 Altitude Sign -: Below sea level
+: Above sea level
0: No reading
32 35 4 Altitude 0000 – 9999: In meters
36 38 3 Heading 000 – 359: In degrees
999: No reading
39 160 * Recipients;Message Comma separated list of recipients, followed by a semicolon,
and then a message. Entire field may be omitted.
Examples:
“support@two10degrees.com,friends;Everything is fine”
“;Everything is fine”
“support@two10degrees.com,friends;”
Example Message
000120523103211+52100+001100030+0012030support@two10degrees.com;Arrived at work

The above example is based on the following information:
Emergeny Flag = 0: Not an Emergency
Message Type = 00: Automatic Position Report
Timestamp = May 23, 2012 10:32:11
Latitude = +52.1
Longitude = +1.1
Speed = 30 km/h
Altitude = 12 m
Heading = 30
Recipients = support@two10degrees.com
Message = Arrived at work

Web Hooks

The Web Hooks Service allows your system to be notified every time a specified action occurs on GAP. We currently support web hooks for Devices, Users, Tenants, MO Messages, and Event Notifications.

To use this service, you need to provide us with the URL of your HTTP endpoint that we will use to POST data. Each item is sent individually soon after the action happens on GAP. The item is serialized using JSON and includes an indicatior of the item type, the action taken, and the item itself. You can choose either basic or no authentication. We have a retry mechanism in place that will repeat the call several times until success HTTP status code is received.

Please contact us if you want to use this service.