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 telemetry updates (no historical or absolute data). 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.

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..." }
});

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.

Subscribing to Events​

Once connected, you can listen for several types of telemetry events:

• telemetry_ua – Unmanned Aircraft telemetry
• telemetry_operator – Operator telemetry
• telemetry_system – System telemetry
• operation – Updates on ongoing operations

For the most up-to-date and comprehensive list of available events, 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. For more details, see the conditions for REST API telemetry requests.

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. If you don't set a viewport, your session won't receive any telemetry data.

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. It's important to debounce these updates to prevent rapid viewport changes, which could lead to the server disconnecting your clients.

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.

For example, to set the viewport to Prague, you may use something like emit("viewport", "14,49.9,15,50.3").

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', () => {
  socket.emit('viewport', viewportRectangle.getBounds().toBBoxString());
});

socket.on('telemetry_ua', (data) => {
  console.log('UA telemetry received:', data);
});

import socketio

sio = socketio.Client()

@sio.event
def connect():
    sio.emit('viewport', viewportRectangle.get_bounds().to_bbox_string())

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

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