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:
Verb | Description |
---|---|
GET | Used to select one or more items. Success returns 200 status code with json result item(s) in body. |
POST | Used to create a new item. Success returns 200 status code with newly created item's Id in body. |
PUT | Used to update an item. Success returns 200 status code with no body. |
DELETE | Used 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
Code | Description |
---|---|
200 | Success. 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.
Code | Description |
---|---|
429 | Too many requests in a given amount of time |
Error codes
Code | Description |
---|---|
unitNotFound | Unit with supplied “Id” was not found. |
clientNotFound | Client with supplied “Id” was not found. |
categoryNotFound | Category with supplied “Id” was not found. |
groupNotFound | Group with supplied “Id” was not found. |
invalidParameter (To) | The history timespan extends the limit. |
zoneNotFound | Zone with supplied “Id” was not found. |
pointNotFound | Point 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:
- SOAP 1.1: https://api.trackunit.com/public/soap11
- SOAP 1.2: https://api.trackunit.com/public/soap12
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 name | Description |
---|---|
string | A sequence of characters |
string[] | A sequence of multiple strings |
int | A number that is not a fraction |
float | Double-precision floating point type |
bool | Logical Boolean type |
DateTime | Time representation |
Compound
The compound data types:
Short name | Description |
---|---|
Location | Consists of 2 float fields:Latitude Longitude |
Address | Consists of 4 string fields:Country (A 2-letter country code) ZipCode City StreetAddress |
AlarmRecipient | Consists of 5 fields: ContactId SentViaPhone Number * Delivered |
TemperatureAlarmLimits | Consists of 4 fields: Temperature1LowerLimit Temperature1LowerLimit Temperature1LowerLimit Temperature1LowerLimit |
ADVoltageAlarmLimits | Consists of 2 fields: ADVoltageLowerLimit ADVoltageUpperLimit |
TimeOfDay | Consists 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
Updated about 2 months ago