PureTrack Insert API

PureTrack provides a simple API endpoint to insert JSON data. To use this you'll need to be issued an insert key for your application. Contact Us to obtain a key.

Make it easier for your users to send safety tracking data to PureTrack without having to use a separate app.

The API is used to insert new data, so your app needs to keep track of what you've already sent to PureTrack.

Multiple trackers and/or location points can be sent in one call, so you can buffer multiple points into a single HTTP request. This reduces the number of requests, and reducing device power by not transmitting data as frequently. For example, you could record locations every 5 seconds, but send to the server every minute.

What we can do for you

Once you get your app sending data to PureTrack:

• We'll add your app in our list of supported trackers.
• We can add a custom configuration page in the PureTrack dashboard for your app.
• We can promote your app as a supported app on our social media.
• We're happy to provide a PureTrack Pro account for you to test with.

Contact us when ready.

Recommended intervals between data points

• 1-2 seconds - not recommended, creates excessive data for no real benefit. Avoid offering as an option to your users.
• 3-5 seconds - good for thermals and accurate corners.
• 5-60 seconds - good for general usage.
• 1-10 minutes - good for location safety and minimal data or minimising battery usage.
• Over 10 minutes - not recommended, people can travel a long way in 10 minutes.
• Variable - ideal. Faster intervals while cornering. Longer intervals while travelling straight lines.

DeviceID

Sending a DeviceID is critical with each call. This is how PureTrack identifies who the data is from.

A user can link multiple data sources to feed into the one PureTrack 'map marker'. To do this they will need to know their DeviceID that you send from your app.

DeviceID guidelines:

• Make the DeviceID short so it's easy to type. e.g. 'd7ry390' instead of '98c19aac-bd29-4301-8970-49a04a8ae542'.
• Display the DeviceID to the user, possibly where they can enable sending to PureTrack.
• Make the DeviceID unique for each device or user.

---

Insert

POST https://puretrack.io/api/insert

Example call, one tracker only.

{ "rego": "ZK-ABC", "label": "asdf", "key": "{YOUR_KEY_GOES_HERE}", "type": 9, "deviceID": "1234", "username": "timbo", "points": [ { "ts": 1713563621, "lat": -41.2334745, "lng": 174.348365, "alt": 345.1, "speed": 25, "course": 270, "vspeed": 5.3 }, { "ts": 1713563624, "lat": -41.1634343, "lng": 174.36545, "alt": 335.1, "speed": 28, "course": 240, "vspeed": 5.1 }, { "ts": 1713563629, "lat": -41.194343, "lng": 174.38545, "alt": 325.1, "speed": 29, "course": 190, "vspeed": 5.0 } ] }

Example call, with one or more trackers. Note the array of items. The key needs to be repeated for each tracker, and is the same for each.

[{ "rego": "ZK-ABC", "label": "Sam ABC", "key": "{YOUR_KEY_GOES_HERE}", "type": 9, "deviceID": "1234", "username": "sambo", "points": [ { "ts": 1713563621, "lat": -41.2334745, "lng": 174.348365, "alt": 345.1, "speed": 25, "course": 270, "vspeed": 5.3 }, { "ts": 1713563624, "lat": -41.1634343, "lng": 174.36545, "alt": 335.1, "speed": 28, "course": 240, "vspeed": 5.1 } ] }, { "rego": "ZK-XYZ", "label": "Jimbo XYZ", "key": "{YOUR_KEY_GOES_HERE}", "type": 9, "deviceID": "4567", "username": "jimbo", "points": [ { "ts": 1713563621, "lat": -41.2334745, "lng": 174.348365, "alt": 345.1, "speed": 25, "course": 270, "vspeed": 5.3 }, { "ts": 1713563624, "lat": -41.1634343, "lng": 174.36545, "alt": 335.1, "speed": 28, "course": 240, "vspeed": 5.1 } ] }]

Returned Results

{ "trackers_received": 2, "total_points_recieved": 6, "total_points_inserted": 5, "time": 29.019832611083984, "success": true, "http_code": 200 }

If some points weren't valid, e.g. missing data, the points inserted will be fewer than the points recieved.

List of parameters

• deviceID - Required. A unique ID or username for your device/user. If a user wants to link this device to other sources in PureTrack they will need to know what this is.
• Rego - Optional. This should only be used to link to a registered aircraft. It should be a full registration e.g. ZK-ABC
• label - Optional. The default label to be displayed on PureTrack. Will not be used if rego is supplied.
• key - Required. your app key.
• type - Optional. A full list of types can be found at https://puretrack.io/types.json.
• username - Optional. UserID on your system. We can optionally link back to your user's account with this ID number.

Point Data

• ts - Required. Timestamp of the data point as an Epoch Unix Timestamp.
• lat - Required. Decimal format.
• lng - Required. Decimal format.
• alt - Optional. Meters.
• speed - Optional. Meters per second.
• vspeed - Optional. Vertical speed. Meters per second.
• course - Optional. Bearing or course. Degrees from 0 to 360

How PureTrack chooses what label to use

1. If a rego is provided, or if the label starts with 'a:' it will link to an aircraft registration e.g. 'a:zk-abc' will link to aircraft 'ZK-ABC'.
2. If a user has configured their DeviceID to a map marker, it will show the name of the map marker and ignore the label completely.
3. If neither of the above is true, it will show the label provided in the API.
4. If there is no label or matching map marker, it will show the raw DeviceID.

This is designed so a user can send to PureTrack from your app without configuring anything at the PureTrack end, but if they want to merge their data with other sources they can.

Registered aircraft vs paragliders

There are two fields you can send: 'rego' and 'label'.

The rego field should only be used for aircraft with a registration i.e. for gliding or powered aircraft.

If you're app is primarily for paragliding or any other activity, you should probably only show the 'label'.

If your app is for both, you might need to let the user choose one or the other. Or as mentioned above, a registration can be inserted into the label field using the 'a:' prefix.