BikeTrax API

The PowUnity tracking server includes a web API to access GPS tracking data from your trackers using a REST API. Documentation for the API can be found in our API Reference which is based on the Swagger format.

There are a lot of tools available to automatically generate a client from a Swagger format. For more information about Swagger see official website - http://swagger.io/.

There are two authorization options:

1. Using session cookies (see "session" URL path)

2. Standard HTTP authorization header

View API documentation:

• API Reference

Access token

As an alternative to email and password login, there is an option to use an account token for authorisation.

The token can be set in the corresponding field of the user model:

The access token can only be used to create a session. It can not be used for the basic authorization option.

To create a token use the "token" query parameter in a session GET request:

https://traccar.powunity.com/api/session?token=YOUR_ACCESS_TOKEN

WebSocket API

In addition to the REST API, we provide access to a WebSocket endpoint for live location updates and events. The URL for the connection:

https://traccar.powunity.com/api/socket

Session cookie is the only authorization option for the WebSocket connection.

Each message in the WebSocket communication uses the same universal JSON format:

{
  "devices": [...],
  "positions: [...],
  "events": [...]
}

Each array contains corresponding standard models:

• Device

• Position

• Event

If message does not contain objects of one of the types, the key would not be included in the JSON structure. Most of the time messages contain a single type of objects.

Sample HTML WebSocket API Client

Here you can find a (non-complete) sample project drawing the devices of an account on a map (including WebSocket live updates).

Sample Node.js WebSocket API Client

We also provide a simple script to subscribe to your BikeTrax event stream and either print it to stdout or process it as you wish. In the sample script we log the events and forward them to a local http endpoint of choice.

This sample project and further documentation can be found here.

Webhook Integration

The BikeTrax Cloud can be configured to call a HTTP(S) endpoint of your choice for every new event generated by your devices' activity.

• Webhooks are sent as HTTP(S) POST

• The Content-Type is application/json

• A X-PowTxn header is set, please log this and quote it for any support queries concerning a specific event.

• The payload is JSON-encoded BikeTrax event data, containing all details the system knows about the Device.

  • Here is an example of an event of type “deviceOnline”,

    {
      "event": {
        "id": 1,
        "attributes": {},
        "deviceId": 1,
        "type": "deviceOnline",
        "serverTime": "2021-01-01T00:00:00.000+00:00",
        "positionId": 0
      },
      "device": {
        "id": 1,
        "attributes": {},
        "groupId": 0,
        "name": "Test Device 1",
        "uniqueId": "1",
        "status": "online",
        "lastUpdate": "2021-01-01T00:00:00.000+00:00",
        "positionId": 0,
        "geofenceIds": [],
        "disabled": false
      }
    }

• The consuming server should respond with HTTP status code either 200 or 201. The HTTP response body is ignored.

• If the webhook fails the BikeTrax Cloud will NOT re-send the data. There is no notification of failed webhooks at this time.

Setting up a webhook

1. Log in to https://traccar.powunity.com

2. click Settings at the top right:

   

3. Select Account

4. Click on the Attributes button in the dialog that opened

5. Use the + button to add the following attributes to the table - NOTE: Attribute names are case sensitive!

   1. webhookUrl This is the URL that will be called on every new event via a HTTP POST request. We highly encourage to use a URL starting with https:// but http:// is also supported for testing purposes.

   2. webhookPsk Optional. If set, the HTTP(S) requests will contain a Authorization header with this attribute’s data as value. This should allow Basic and Bearer authorization methods to be implemented easily.

   3. webhookTypes Optional. If set, this should be a comma (,) separated list of event types which are to be forwarded by the webhook. If this attribute is not present then all events are sent. Some useful possible values are: deviceOnline, deviceOffline, deviceMoving, deviceStopped, alarm, geofenceEnter, geofenceExit, ignitionOn, ignitionOff

   4. Here is what the Attributes dialog could look like:

      

6. Once the attributes are set close the Attributes and Account dialogs. The webhooks are then activated immediately.