Skip to main content

Unified JSON Format

Dronetag data normally arrives as separate messages: the aircraft position, the operation it belongs to, the operator position and the device status each come on their own, and your system has to put them back together.

Unified JSON does that for you. Each aircraft arrives as one record that already contains its latest position, its operation details and its operator position. It is the easiest format to start with if you are building your own integration.

info

Unified JSON is available only with HTTP Webhooks.

What you receive​

Dronetag sends a POST request with one JSON object. With Throttle messages enabled, you get one request per throttle interval; without it, requests are sent as fast as data arrives, so each holds only a few records. The object contains two lists:

  • ua - one record per aircraft, with its most recent position.
  • system - one record per device (Remote ID module, receiver, ...), with its battery, GPS and mobile-signal status.
{
"ua": [
{
"type": "ua",
"timestamp": "2026-09-14T10:15:02.120000Z",
"sensor_id": "1596F3A1B2C3D4E5F6",
"integration_client_id": "customer-42",
"ua": {
"operational_state": "airborne",
"location": { "latitude": 50.0755, "longitude": 14.4378 },
"altitude": { "msl": 312.4, "agl": 45.1, "ato": null, "hae_wgs84": null, "pa_qne": null },
"velocity": { "heading": 182.0, "horizontal_speed": 7.5, "vertical_speed": -0.3, "components": [-0.26, -7.49, -0.3] },
"air_pressure": null
},
"operation": {
"id": "7c1e2f4a-...",
"status": "current",
"uas_operator_id": "CZEabc123def456",
"identifiers": {
"serial_number": "1596F3A1B2C3D4E5F6",
"caa_assigned": null,
"utm_assigned": null,
"specific_session_id": null,
"callsign": "SURVEY-1"
},
"classification": { "type": "european_union", "category": "open", "class": "class_1" },
"descriptions": { "text": "Roof inspection", "emergency": null, "extended_status": null, "color": null },
"warnings": [],
"transmission_technology": "bluetooth_legacy"
},
"operator": {
"timestamp": "2026-09-14T10:14:58Z",
"location": { "latitude": 50.0761, "longitude": 14.4369 },
"altitude": { "msl": null, "agl": null, "ato": null, "hae_wgs84": 312.0, "pa_qne": null },
"source_type": "take_off"
}
}
],
"system": [
{
"type": "system",
"timestamp": "2026-09-14T10:15:01Z",
"sensor_id": "1596F3A1B2C3D4E5F6",
"integration_client_id": "customer-42",
"operation_id": null,
"system_type": "rid_module",
"status": "operational",
"location": { "latitude": 50.0755, "longitude": 14.4378 },
"altitude": { "msl": null, "agl": null, "ato": null, "hae_wgs84": 312.0, "pa_qne": null },
"power_source": { "type": "battery", "input_voltage": 3.9, "charge_percentage": 82, "is_being_charged": false },
"lte": { "status": "connected", "rsrq": -10.0, "rsrp": -95.0, "snr": 12.0, "tac": 1234, "cell_id": 56789 },
"gnss": { "status": "connected", "satellites": 14 }
}
]
}

A few rules make the data easy to process:

  • Within your distribution, every record has the same keys. A value that is not known yet is null - for example, the operation details at the very start of a flight. Records sent later fill them in.
  • Each aircraft appears once per request (once per flight), with its newest position. If you need every position, see interim below.
  • Both lists are always present, [] when one has nothing to send. A request with both lists empty is sent only if Send empty payloads is enabled.
  • Ignore record types you do not recognise. New types may be added in the future.
Possible values
KeyValues
ua.operational_stategrounded, airborne, emergency
operation.statuspast, current, upcoming
operation.classificationtype: european_union; category: open, specific, certified; class: class_0 - class_6
operation.warningslist of { "code", "additional_context" }, e.g. code invalid_uas_id
operation.transmission_technologywifi_beacon, wifi_nan, bluetooth_legacy, bluetooth_long_range, ads_l, ocusync, external, ...
operator.source_typetake_off, dynamic, fixed
system_typerid_module, rid_standard, rid_receiver, funnel_service, proxy
status (device)operational, degraded, error
power_source.typeunknown, battery, mains, poe
lte.status, gnss.statusconnected, degraded, not_ready, disconnected

sensor_id is the serial number of the device that sent the data. Altitudes are in metres; msl is above mean sea level, agl above ground, ato above take-off, hae_wgs84 above the WGS84 ellipsoid and pa_qne pressure altitude.

Identifying your users​

If your distribution uses a Partner Integration data source, users may enter an identifier when they enable your integration in the Dronetag App - for example, their account number in your system.

Every record then carries that identifier in integration_client_id, so you can match each aircraft and device to the right user, even when one request contains the data of many users. The value is null when the user did not enter anything, and always null for other data sources.

note

Over HTTP, other output formats send this identifier in the X-Integration-Client-Id HTTP header. Unified JSON does not send that header; use the value in the record instead.

Optional settings​

You can adjust the format in the distribution's specific configuration in the integration portal, next to any HTTP settings such as target_additional_http_headers. Everything is optional.

{
"fields": ["ua", "operation", "operator.location", "integration_client_id"],
"exclude": ["operation.warnings"],
"interim": false,
"distribute_operator_telemetry": true,
"distribute_system_telemetry": true
}
SettingWhat it doesDefault
fieldsSends only the listed parts of the aircraft record. Use dots for nested values, e.g. operator.location. type, timestamp, sensor_id and operation.id are always sent.the whole record
excludeRemoves the listed parts from what fields selected.nothing removed
interimtrue also sends the older records from the same request, oldest first: earlier aircraft positions in ua_interim, earlier operator positions in operator_interim and earlier device states in system_interim.false
distribute_operator_telemetryfalse leaves operator always null.true
distribute_system_telemetryfalse leaves the system list always empty.true

fields and exclude apply only to aircraft records; device records are always sent whole. If you use fields with a Partner Integration, include integration_client_id in the list.

If a setting is invalid, the distribution does not start and the error is shown in the integration portal. This happens when a path does not exist, when an exclude path is not inside fields, or when exclude would remove an always-sent key - for example exclude: ["operation"], because operation.id is always sent; use exclude: ["operation.warnings"] and similar instead.