The REST API is best for retrieving absolute current & historical telemetry data, accessing account data such as assets, devices, aircraft and more. Because you need to request data manually, it's not very suitable for real-time data streaming. For real-time data, we recommend looking at using our Socket.io endpoints.

Obtaining API Credentials​

To access our API, you’ll need to authenticate. There are two ways to do this:

1. Personal Token: Use your personal token to access data on your Dronetag account. This can be created in our app or using API.
2. OpenID Connect: Use OIDC for more advanced authentication methods and allowing your application to access other users' private data.

Consuming the API​

Once you have your credentials, you’re ready to start using the API. We recommend familiarizing yourself with the API documentation, which outlines all available endpoints and the data structures you’ll be working with.

Understanding DUMP data format​

Our API uses a variety of data schemas, each designed for a specific API resource. One of them is used more consistently across our services, and that is the Dronetag Unified Message Protocol (DUMP) format. If you're dealing with Remote ID data, this protocol will be particularly important to understand.

To help you better understand, we've created a detailed guide that breaks down the structure of DUMP messages and explains how to work with them effectively:

Conditions for Telemetry Request Parameters​

Keep in mind that when making telemetry requests to our airspace endpoints (/v2/airspace/*), you must specify both a time range (from and to) and a geographical region (bbox).

There are a few exceptions to this requirement:

• If you provide an operation_id, no other parameters are needed.
• If you specify a uas_id, you can omit the bbox geographical region, but the time range is still required.

Please note that the bbox size is limited and intended for moderately sized regions. It is not possible to use bbox to cover large areas such as entire countries, continents, or the world.

If this condition poses a challenge, we recommend exploring our data push methods.

Additional Guides​

We offer several other guides to help you navigate common use cases with our API. Whether you’re looking to retrieve current airspace information or historical data, these resources will give you the tools you need:

Explore more guides through the left sidebar to enhance your API usage.

The Socket.io API is designed for real-time telemetry data streaming, offering only live updates (no historical or absolute data). Data you miss while disconnected are not replayed — to get the current state or fill gaps after a reconnect, use the REST API. This guide will walk you through setting up a real-time connection between Dronetag and your application using Socket.io.

Connection Parameters​

To establish a connection, use the following configuration parameters in your Socket.io client:

• Host: https://api.dronetag.app
• Path: /v2/airspace/socket.io
• Client Version: v3 or v4

Choosing a Socket.io Client​

Socket.io is supported by many libraries across various programming languages. You can find the full list of supported client implementations here.

Authenticating Your Session​

You can authenticate your Socket.io session using the same access token that you use for REST API requests. Refer to the API credentials guide for details on obtaining your access token.

Authentication is optional. A session without a token receives only publicly available data, while an authenticated session also receives the data your account has access to.

If the token you send is not valid, the server refuses the connection and your client receives a connect_error with the message unauthorized.

Native Socket.io Authentication​

For clients that support native Socket.io authentication, you can pass the access token directly in the auth configuration option.

let socket = io("https://api.dronetag.app", {
  path: "/v2/airspace/socket.io",
  auth: "eyJhbGciOiJSUzI1NiIsInR5c...",
});

More information on using Socket.io authentication can be found in the Socket.io documentation.

Using a Bearer Token in the Handshake Request​

If your client does not support the auth option, you can send the access token as an Authorization header in the handshake request:

let socket = io("https://api.dronetag.app", {
  path: "/v2/airspace/socket.io",
  extraHeaders: { Authorization: "Bearer eyJhbGciOiJSUzI1NiIsInR5c..." }
});

The header value must be in the form Bearer <token>, otherwise the connection is refused with the message wrong bearer token format.

This approach is also handy when using tools like Postman for testing, which typically don’t support native authentication. You can simply add the Authorization header in the Headers tab of Postman.

Authenticating an Existing Connection​

You can also authenticate an already established connection by sending the access token in the authenticate event. The server acknowledges it with {"result": "ok"}. If the token is not valid, the server responds with {"result": "not_authenticated"} and the connection stays open as unauthenticated, receiving only publicly available data.

Subscribing to Events​

Once connected, you can listen for the following events:

• serverinfo – Sent once, right after the connection is established. Contains information about the server, such as server_version, environment and your_sid (your session ID as seen by the server).
• telemetry_ua – Unmanned Aircraft telemetry
• telemetry_operator – Operator telemetry
• telemetry_system – System telemetry
• operation – Operation updates

Each telemetry_ua, telemetry_operator, telemetry_system and operation event carries an array of DUMP messages, not a single message. Telemetry events are limited to the viewport you set (see below), while operation events are not limited by the viewport. The operation event carries OperationUpdate messages, which contain only recent changes of an operation, not its full state.

For the most up-to-date and comprehensive list of available events, their payloads and responses, refer to our AsyncAPI documentation.

Setting and Updating the Viewport​

Just as with the REST API, you must specify the geographical region your application is interested in.

After connecting, your client must send an initial viewport event to define the geographical area it wants to monitor. Additionally, the client must update this area by sending new viewport events whenever the region of interest changes. Each viewport event replaces the previously set viewport. If you don't set a viewport, your session won't receive telemetry for any area.

The viewport is bound to a single connection. Whenever your client connects or reconnects, it must send the viewport again.

The viewport is a string in the format lon_min,lat_min,lon_max,lat_max — longitude and latitude in degrees, separated by commas without spaces. For example, to set the viewport to Prague, you may use something like emit("viewport", "14,49.9,15,50.3").

For example, in Dronetag’s own applications, the map moves dynamically based on user interactions. After establishing a connection, the app sends the initial viewport, and as the user moves the map, the viewport is updated. We recommend debouncing these updates, so that your client does not send a new viewport on every small map movement.

Always set your viewport carefully. It is important to cover the whole area of your interest. On the other hand, do not set viewports too large, as it could provide data you do not want and also cause performance issues. It is recommended to add a sufficient margin of a few kilometers (or miles, if you wish) on each side. The maximal supported viewport area is around 6 million square kilometers, but try avoiding such extreme values.

The server acknowledges each viewport event with one of these responses:

• {"result": "ok"} – The viewport was set.
• {"result": "invalid-param", "messages": [...]} – The viewport is not in the expected format or its values are out of range.
• {"result": "bbox_area_too_large", "messages": [...]} – The viewport area exceeds the maximal supported area. The previously set viewport stays in effect.

To read the response, pass an acknowledgement callback when emitting the event, for example socket.emit("viewport", "14,49.9,15,50.3", (response) => console.log(response)).

Ordering Telemetry​

By default, telemetry within each event is ordered by time in ascending order. You can change the ordering for each telemetry event by sending the ordering event. Its payload must be a JSON-encoded string mapping the event names to one of these values:

• time – ascending order (default)
• -time – descending order

socket.emit("ordering", JSON.stringify({
  telemetry_ua: "-time",
  telemetry_operator: "time",
  telemetry_system: "time",
}));

The server acknowledges the event with {"result": "ok"}, or with {"result": "invalid-param", "messages": [...]} if the payload is not valid. Like the viewport, the ordering is bound to a single connection.

Example Code Snippets​

Below are some quick examples to help you get started with Socket.io in different programming languages:

const { io } = require('socket.io-client');

const socket = io('https://api.dronetag.app', {
  path: '/v2/airspace/socket.io',
  auth: 'eyJhbGciOiJSUzI1NiIsInR5c...'
});

socket.on('connect', () => {
  // The viewport must be sent after every (re)connect
  socket.emit('viewport', '14,49.9,15,50.3', (response) => {
    console.log('Viewport response:', response);
  });
});

socket.on('connect_error', (err) => {
  console.error('Connection error:', err.message);
});

socket.on('telemetry_ua', (batch) => {
  for (const telemetry of batch) {
    console.log('UA telemetry received:', telemetry);
  }
});

import socketio

sio = socketio.Client()

@sio.event
def connect():
    # The viewport must be sent after every (re)connect
    sio.emit(
        'viewport',
        '14,49.9,15,50.3',
        callback=lambda response: print(f'Viewport response: {response}'),
    )

@sio.event
def connect_error(data):
    print(f'Connection error: {data}')

@sio.event
def telemetry_ua(batch):
    for telemetry in batch:
        print(f'UA telemetry received: {telemetry}')

sio.connect(
    'https://api.dronetag.app',
    socketio_path='/v2/airspace/socket.io',
    auth='eyJhbGciOiJSUzI1NiIsInR5c...'
)

sio.wait()

Here, you will learn how to authenticate your requests to access resources available on Dronetag accounts.

We offer two authentication methods: Personal Access Tokens (PATs) and OpenID Connect. Each method serves different use cases, so please read on to determine which is best suited for your project.

Using Personal Access Tokens (PATs)​

If you plan to work with personal data from your own Dronetag account, such as post-processing data, creating a personal command-line interface (CLI) tool, or integrating data into other software, Personal Access Tokens (PATs) are available for easy and straightforward access to the API.

These tokens provide a simple to use, although less secure, method for accessing your resources via our API services. For more robust integrations intended for public access, we recommend considering the OpenID Connect method instead.

Creating a new token​

{
    "password": "hunter2",
    "expires_at": "2025-09-09"
}

After you issue a new Personal Access Token, be sure to store this token securely. You won't be able to retrieve this token again.

Using tokens to authorize requests​

You can now use the token in X-Personal-Access-Token HTTP header when making requests.

Example request with PAT​

POST /v2/airspace/telemetry/ua HTTP/1.1
Host: api.dronetag.app
Accept: */*
X-Personal-Access-Token: 4c5250130bbce349.b0dc901facd944e999b32ebf984c5250130bbce349b0dc901facd944e999b32e

Implementing OpenID Connect​

By implementing Sign in with Dronetag, you can allow users to access their data through your application. This method is more reliable and offers a standardized approach to authentication.

Understanding OpenID Connect (OIDC)​

Our implementation is based on OpenID Connect (which should not be confused with OpenID). OIDC allows you to leverage existing libraries and may already be supported by your application. Learn more on the OpenID Foundation website.

To utilize OIDC in your application, you will need your own client ID and secret. If you have not yet received these credentials, please contact us for assistance.

Implement authentication in your application​

curl -X POST "https://auth.dronetag.app/realms/dcp/protocol/openid-connect/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=password" \
-d "client_id=<your-client-id>" \
-d "client_secret=<your-client-secret>" \
-d "username=<your-username>" \
-d "password=<your-password>"

{
    "access_token": "eyJhbGc...",
    "expires_in": 1200,
    "refresh_expires_in": 604800,
    "refresh_token": "eyJhbGc...",
    "token_type": "Bearer",
    "not-before-policy": 0,
    "session_state": "35d764ee-c27c-4763-bc05-5ffa2e2b822e",
    "scope": "email"
}

The table above assumes your application has been assigned its "Client ID" and "Client Secret". For testing purposes, you may use a generic Client ID of dronetag-integration-test with no secret needed. For production use, each individual application should be assigned its own unique Client ID. Otherwise, limits on the volume of pulled data may be applied. Contact Dronetag support to get your credentials.

Using Access Tokens​

Both Personal Access Tokens and access tokens retrieved using OIDC can be added as a Bearer token in the Authorization header to authenticate your API requests.

Example Request​

POST /v2/airspace/telemetry/ua HTTP/1.1
Host: api.dronetag.app
Accept: */*
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICItQllNT2...

Refreshing Tokens​

Access tokens issued as JWTs are short-lived and require refreshing upon expiration. We recommend reviewing the following resources for more information on refresh tokens and their secure usage:

• What Are Refresh Tokens and How to Use Them Securely - Auth0
• Understanding Refresh Tokens, Access Tokens, and ID Tokens in OIDC Protocol - Logto
• Refresh Access Tokens and Rotate Refresh Tokens - Okta