How does the burnair Live Tracking API work?

Please contact burnair before you start sending data - we would like to understand your project and discuss the details of it. Furthermore we need to discuss the "source", the "deviceId" as well as the expected traffic.

Authentication

Request

• https://api.burnair.cloud/v1/auth
• POST Request
• Payload: {username: "test@gmail.com", password: "******"}

Reply 

{"token_type":"Bearer","expires_in":2563200,"access_token":"<TOKEN in JWT>"}

expires_in is when the token needs to be re-requested (in seconds)

Sending Tracking Data

In order to successfully send tracking data, a burnair Map contract is required (burnair Map Tracking Plus or burnair Map Premium).

Request

• https://api.burnair.cloud/v1/liveTracking
• POST Request
• authorization: Bearer <TOKEN in JWT> (see above)
• Minimum Payload (e.g. for two positions):
  
  [{"epoch": 1646541872, "typeId": 7001, "lng": 8.708055, "lat": 47.4826, "source": "test"}, {"epoch": 1646541882, "typeId": 7001, "lng": 8.708055, "lat": 47.4826, "source": "test"} ]

Reply (Status Code)

• 204 - No content (all good)
• 400 - Payload not valid
• 404 - No contract
• 500 / 502 - Server error

Tracking Data Payload

Required data

• epoch - Seconds since unix time (UTC!)
  Unit: seconds (s)
  Type: integer
  Precision: 0
  Only current epochs are permitted - old data cannot be uploaded
• lng - Longitude
  Unit: degrees (°)
  Type: number
  Precision: Min 4. decimals.
• lat
  Unit: degrees (°)
  Type: number
  Precision: Min 4. decimals
• source - where the data is coming from
  Type: string
  Max Length: 10
  Examples: ba, bw, bg, sn, oj, of, fm
  Do not use any of the above short codes - request burnair to give you a source id

Further data

* This data is very much recommended

• * deviceId
  Type: string
  Examples: 11,123; ba,123; fm,123
  This device id must be unique for the world!
• * type - is the instrument in the air (1) or on the ground (7)
  Type: enum (1, 7) - see below
  Default: 1
  Example 7
• * subtype - what activity is the instrument doing (depending on type)
  Type: enum (1, 2, ..) - see below
  Default: 7
  Example: 9
• * typeId - used as alternative to type and subtype
  Type: enum (7001, 7002, 7009, 1001 etc)
  Default: 7001
  Example: 7009
  The typeId is composed from type and subtype where as type is one character and subtype is four characters.
• * altitude
  Unit: meters (m)
  Type: integer
  Example: 1546
  When device is on the ground, altitude is not considered, thus does not have to be provided
• * hSpeed - horizontal speed of the instrument
  Unit: kilometers per hour (km/h)
  Type: decimal
  Precision: 1
  Example: 35.7
• * vSpeed - vertical speed of the instrument
  Unit: meters per second (m/s)
  Type: number
  Precision: 1
  Example: -1.1
• * heading - heading of movement
  Unit: degrees (°)
  Type: integer
  Example: 246
• agl
  Unit: meters (m)
  Type: integer
  Example: 245
  Report amount of meters above the ground the device is (0m agl = standing on the ground).
  Minus values are not permitted (0 is the lowest possible number)
  Dont set for any ground based activities - type 7 (e.g. hiking)
  Only provide if agl data is 30m srtm with bilinear interpolation or better
• tracking - does the instrument want to be tracked (1) or not (0)
  Type: enum (0, 1)
  Default: 1
• hAccuracy
  Unit: meters (m)
  Type: integer
  Example: 23
• vAccuracy
  Unit: meters (m)
  Type: integer
  Example: 12
• sourceId - which device / groundstation is gathering the data
  Type: string
  Max Length: 10
  Example: id of groundstation, id of fanet device when acting as hotspot
• sourceRaw - for debugging
  Type: string
  Max Length: 255

Future data (not yet implemented)

• batteryLevel
• pressure

Important notes

• When certain data is not available it shall not be transmitted
• Example: vSpeed 0 is not equal to vSpeed null - if vSpeed is 0 the flying object maintains the altitude. If vSpeed is not transmitted it means that the instrument does not have the vSpeed.
• The tracking interval on the ground (type = 7) is 1/10 seconds, in the air (type = 1) its 1/1.

Most important Tracking Subtypes

Air Tracking (when type = 1)

Only Paraglider is supported for now.

• 0   Other (not supported)
• 1   Paraglider
• 2   Hangglider (not supported!)

Ground Tracking (when type = 7)

• 0   Other
• 1   Hiking
• 2   Vehicle
• 3   Bicycle
• 4   Boat
• 8   Looking for a ride
• 9   Landed well
• 12 Need technical help
• 13 Need medical help
• 14 SOS Emergency
• (More on request)