Access Classic APIs

The base URL of the API is: https://api.trackunit.com/public
Metadata can be viewed on: https://api.trackunit.com/public/metadata

Feel free to point your browser to the APIs base url, and navigate the API to see how it works.

❗️

Access to Classic API tokens is restricted

Because the Classic API suite is build on our legacy architecture and will not be developed further, we have now restricted the creation of new API authentication tokens. We encourage you to use our new IRIS platform and API suite instead. If you still have the need to obtain a token for the classic APIs, then you can send a formal request to your Trackunit account contact and explain your situation.

General

The API supports different means to call:

 

Authentication

Permission to the API service is granted by use of an authentication token.

📘

Important

The API token must remain secret. You shouldn’t share it with anybody, as it grants access to all your organization’s data. Keep it safe like your normal password.

Basic access authentication

Use “API” as username and your authentication token as password.

Authentication passed by URL

You are also able to pass your authentication token to the URL itself.

As an example: https://api.trackunit.com/public/GetUnit?token=2D0DDB5DA32E40B382EF1E8B823E1F3D

 

Protocol specification

Details on the protocol and approaches supported.

📘

Important

All examples in this documentation are based on HTTPS calls.

REST

With REST, you specify action in HTTP verb:

VerbDescription
GETUsed to select one or more items. Success returns 200 status code with json result item(s) in body.
POSTUsed to create a new item. Success returns 200 status code with newly created item's Id in body.
PUTUsed to update an item. Success returns 200 status code with no body.
DELETEUsed to delete an item. Success returns 200 status code with no body.

Status codes

All API responses will be returned with the following code:

Success codes

CodeDescription
200Success. Request completed.

Rate limiting

Current limit rule is 50 requests per second. Exceeding the limit will delay the requests for up to 3 seconds. The maximum delay queue is 200 requests.

CodeDescription
429Too many requests in a given amount of time

Error codes

CodeDescription
unitNotFoundUnit with supplied “Id” was not found.
clientNotFoundClient with supplied “Id” was not found.
categoryNotFoundCategory with supplied “Id” was not found.
groupNotFoundGroup with supplied “Id” was not found.
invalidParameter (To)The history timespan extends the limit.
zoneNotFoundZone with supplied “Id” was not found.
pointNotFoundPoint with supplied “Id” was not found.

🚧

Important

There is a maximum timespan of 31 days for API calls.

Response envelope

All API responses will be returned in the following envelope:

{
   "list":[
      {
         "alarmId": 70329,
            "unitId": 34333,
            "triggeredAt": "2014-03-05T07:00:02.7421152Z",
            "address": {
                "country": "DK",
                "zipCode": "3000",
                "city": "Helsingør",
                "streetAddress": "Haderslevvej 16F"
            },
            "location": {
                "latitude": 56.025985,
                "longitude": 12.5903716666667
            }
        },
        {
            "alarmId": 70329,
            "unitId": 39670,
            "triggeredAt": "2014-03-05T07:00:02.7421152Z",
            "address": {
                "country": "DK",
                "zipCode": "2990",
                "city": "Nivå",
                "streetAddress": "Margerittens Kvarter 51"
            },
            "location": {
                "latitude": 55.9451516666667,
                "longitude": 12.4999066666667
            }
        },
        {
            "alarmId": 70329,
            "unitId": 46208,
            "triggeredAt": "2014-03-05T07:00:02.7421152Z",
            "address": {
                "country": "DK",
                "zipCode": "2740",
                "city": "Skovlunde",
                "streetAddress": "Harrestrupvej 166"
            },
            "location": {
                "latitude": 55.7004533333333,
                "longitude": 12.374295
            }
        },
        {
            "alarmId": 70329,
            "unitId": 46209,
            "triggeredAt": "2014-03-05T07:00:02.7421152Z",
            "address": {
                "country": "DK",
                "zipCode": "3060",
                "city": "Espergærde",
                "streetAddress": "Strandvejen 143A"
            },
            "location": {
                "latitude": 55.99636,
                "longitude": 12.5639
            }
        }
   ]
}

List

list contains the resource object for a success, status code 200.

Output format

The API supports 4 response formats

  • json
  • xml
  • soap 1.1/1.2
  • html

REST endpoints

You can define which format you would like returned by adding a .{format} extension:

  • .json
  • .xml
  • .html

Or by appending ?format={format} to the end of the URL:

  • ?format=json
  • ?format=xml
  • ?format=html

Example: https://api.trackunit.com/public/GetUnit?token=2D0DDB5DA32E40B382EF1E8B823E1F3D&format=json

Alternatively the API also recognizes which format should be used with the Accept http header:

  • Accept: application/json
  • Accept: application/xml

As you can see, this approach only works with json and xml.

SOAP endpoints

The SOAP endpoint only supports XML of course.

SOAP

If you prefer to use SOAP to access API, use your favorite tool (i.e. Visual Studio) to generate client classes from WSDL:

In this case, you need to examine the response's ResponseStatus field manually, to see if the request was executed successfully.

If this field is present in response (not null), you may check ErrorCode and Message attributes to find the reason of failure.

 

Data types

An overview of data types utilized in the API, meaning both built-in data types as well as compound data types.

Built-in

The built-in data types:

Short nameDescription
stringA sequence of characters
string[]A sequence of multiple strings
intA number that is not a fraction
floatDouble-precision floating point type
boolLogical Boolean type
DateTimeTime representation

Compound

The compound data types:

Short nameDescription
LocationConsists of 2 float fields:
Latitude
Longitude
AddressConsists of 4 string fields:
Country (A 2-letter country code)
ZipCode
City
StreetAddress
AlarmRecipientConsists of 5 fields:
ContactId
SentViaPhone
Number
Email
* Delivered
TemperatureAlarmLimitsConsists of 4 fields:
Temperature1LowerLimit
Temperature1LowerLimit
Temperature1LowerLimit
Temperature1LowerLimit
ADVoltageAlarmLimitsConsists of 2 fields:
ADVoltageLowerLimit
ADVoltageUpperLimit
TimeOfDayConsists of 2 fields:
Hour
Minute
 

Demo project

We encourage you to try out the demo project.

The demo project has been designed to provide you with a basic understanding of how the API works.

The demo project is a range of C#/Visual Studio project files, which will exemplify both following approaches:

Download

Please use the following link to download the demo project package:
API demo project