REST API se nejlépe hodí k získání aktuálních i historických telemetrických dat a k přístupu k datům účtu, jako jsou prostředky (assets), zařízení, letadla a další. Protože si data musíte sami vyžádat, není příliš vhodné pro streamování dat v reálném čase. Pro data v reálném čase doporučujeme naše endpointy Socket.io.

Získání přihlašovacích údajů k API​

Pro přístup k našemu API se musíte ověřit. Máte dvě možnosti:

1. Osobní token: Osobním tokenem získáte přístup k datům na svém účtu Dronetag. Vytvoříte ho v naší aplikaci nebo přes API.
2. OpenID Connect: OIDC slouží k pokročilejšímu ověřování a umožní vaší aplikaci přistupovat k soukromým datům jiných uživatelů.

Používání API​

Jakmile máte přihlašovací údaje, můžete API začít používat. Doporučujeme se nejprve seznámit s dokumentací API, která popisuje všechny dostupné endpointy a datové struktury, se kterými budete pracovat.

Datový formát DUMP​

Naše API používá řadu datových schémat, každé pro konkrétní prostředek API. Jedno z nich se ale napříč našimi službami používá nejjednotněji: formát Dronetag Unified Message Protocol (DUMP). Pokud pracujete s daty Remote ID, je pro vás porozumění tomuto protokolu obzvlášť důležité.

Připravili jsme podrobný návod, který rozebírá strukturu zpráv DUMP a vysvětluje, jak s nimi efektivně pracovat:

Podmínky pro parametry telemetrických požadavků​

Při telemetrických požadavcích na endpointy vzdušného prostoru (/v2/airspace/*) musíte vždy zadat časový rozsah (from a to) i geografickou oblast (bbox).

Z tohoto pravidla existuje několik výjimek:

• Pokud zadáte operation_id, žádné další parametry nejsou potřeba.
• Pokud zadáte uas_id, můžete vynechat geografickou oblast bbox, časový rozsah je ale stále povinný.

Velikost bbox je omezená a je určená pro středně velké oblasti. Pomocí bbox nelze pokrýt velká území, jako jsou celé státy, kontinenty nebo celý svět.

Pokud je pro vás tato podmínka problémem, doporučujeme podívat se na způsoby, jak vám data posíláme (Data Push).

Další návody​

Pro běžné případy použití našeho API máme několik dalších návodů. Ať už chcete získat aktuální stav vzdušného prostoru, nebo historická data, najdete v nich vše potřebné:

Další návody najdete v levém postranním panelu.

API Socket.io je určené ke streamování telemetrických dat v reálném čase a poskytuje jen živé aktualizace (žádná historická ani absolutní data). Data, která zmeškáte během odpojení, se znovu neposílají — aktuální stav nebo chybějící data po opětovném připojení získáte přes REST API. Tento návod vás provede navázáním spojení v reálném čase mezi Dronetagem a vaší aplikací přes Socket.io.

Parametry spojení​

Ke spojení použijte ve svém klientovi Socket.io tyto konfigurační parametry:

• Host: https://api.dronetag.app
• Path: /v2/airspace/socket.io
• Verze klienta: v3 nebo v4

Výběr klienta Socket.io​

Socket.io podporuje řada knihoven v mnoha programovacích jazycích. Úplný seznam podporovaných klientských implementací najdete zde.

Ověření relace​

Relaci Socket.io ověříte stejným přístupovým tokenem, jaký používáte pro požadavky na REST API. Jak přístupový token získat, popisuje návod k přihlašovacím údajům k API.

Ověření není povinné. Relace bez tokenu dostává jen veřejně dostupná data, ověřená relace navíc i data, ke kterým má přístup váš účet.

Pokud pošlete neplatný token, server spojení odmítne a váš klient dostane connect_error se zprávou unauthorized.

Nativní ověření v Socket.io​

U klientů, které podporují nativní ověřování Socket.io, můžete přístupový token předat přímo v konfigurační volbě auth.

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

Více o ověřování v Socket.io najdete v dokumentaci Socket.io.

Bearer token v úvodním požadavku (handshake)​

Pokud váš klient volbu auth nepodporuje, můžete přístupový token poslat v hlavičce Authorization úvodního požadavku (handshake):

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

Hodnota hlavičky musí mít tvar Bearer <token>, jinak server spojení odmítne se zprávou wrong bearer token format.

Tento postup se hodí i při testování v nástrojích, jako je Postman, které nativní ověřování obvykle nepodporují. Stačí přidat hlavičku Authorization na kartě Headers v Postmanu.

Ověření navázaného spojení​

Ověřit můžete i spojení, které už je navázané: pošlete přístupový token v události authenticate. Server ji potvrdí odpovědí {"result": "ok"}. Je-li token neplatný, server odpoví {"result": "not_authenticated"} a spojení zůstane otevřené jako neověřené, takže dostává jen veřejně dostupná data.

Odběr událostí​

Po připojení můžete naslouchat těmto událostem:

• serverinfo – posílá se jednou, hned po navázání spojení. Obsahuje informace o serveru, například server_version, environment a your_sid (ID vaší relace, jak ho vidí server).
• telemetry_ua – telemetrie bezpilotního letadla (UA)
• telemetry_operator – telemetrie operátora
• telemetry_system – systémová telemetrie
• operation – změny operací

Každá událost telemetry_ua, telemetry_operator, telemetry_system a operation nese pole zpráv DUMP, ne jednu zprávu. Telemetrické události jsou omezené na nastavený viewport (viz níže), události operation viewport neomezuje. Událost operation nese zprávy OperationUpdate, které obsahují jen nedávné změny operace, ne její úplný stav.

Nejaktuálnější a úplný seznam dostupných událostí, jejich obsahu a odpovědí najdete v naší dokumentaci AsyncAPI.

Nastavení a aktualizace výřezu (viewport)​

Stejně jako u REST API musíte zadat geografickou oblast, o kterou se vaše aplikace zajímá.

Po připojení musí váš klient poslat úvodní událost viewport, která určí sledovanou geografickou oblast. Kdykoli se oblast zájmu změní, musí klient oblast aktualizovat novou událostí viewport. Každá událost viewport nahradí dříve nastavený viewport. Pokud viewport nenastavíte, relace nedostane telemetrii z žádné oblasti.

Viewport platí jen pro jedno spojení. Při každém připojení i opětovném připojení ho klient musí poslat znovu.

Viewport je řetězec ve tvaru lon_min,lat_min,lon_max,lat_max — zeměpisná délka a šířka ve stupních, oddělené čárkami bez mezer. Viewport nastavený například na Prahu může vypadat takto: emit("viewport", "14,49.9,15,50.3").

V aplikacích Dronetagu se například mapa dynamicky posouvá podle toho, co uživatel dělá. Po navázání spojení pošle aplikace úvodní viewport a při posouvání mapy ho aktualizuje. Doporučujeme tyto aktualizace tlumit (debounce), aby klient neposílal nový viewport při každém drobném posunu mapy.

Viewport vždy nastavujte uvážlivě. Musí pokrýt celou oblast vašeho zájmu, ale zároveň nesmí být zbytečně velký — dostávali byste data, která nechcete, a mohly by nastat problémy s výkonem. Doporučujeme přidat na každé straně dostatečnou rezervu několika kilometrů. Největší podporovaná plocha viewportu je zhruba 6 milionů km², takovým extrémním hodnotám se ale raději vyhněte.

Server každou událost viewport potvrdí jednou z těchto odpovědí:

• {"result": "ok"} – viewport je nastavený.
• {"result": "invalid-param", "messages": [...]} – viewport nemá očekávaný tvar nebo jsou jeho hodnoty mimo povolený rozsah.
• {"result": "bbox_area_too_large", "messages": [...]} – plocha viewportu přesahuje největší podporovanou plochu. Dál platí dříve nastavený viewport.

Odpověď přečtete tak, že při odeslání události předáte callback pro potvrzení (acknowledgement), například socket.emit("viewport", "14,49.9,15,50.3", (response) => console.log(response)).

Řazení telemetrie​

Ve výchozím stavu je telemetrie v každé události seřazená vzestupně podle času. Řazení můžete pro každou telemetrickou událost změnit událostí ordering. Jejím obsahem musí být řetězec v kódování JSON, který názvům událostí přiřadí jednu z těchto hodnot:

• time – vzestupně (výchozí)
• -time – sestupně

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

Server událost potvrdí odpovědí {"result": "ok"}, nebo {"result": "invalid-param", "messages": [...]}, pokud obsah není platný. Stejně jako viewport platí i řazení jen pro jedno spojení.

Ukázky kódu​

Níže je několik krátkých ukázek, které vám se Socket.io pomohou začít v různých programovacích jazycích:

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()

Na této stránce se dozvíte, jak ověřovat požadavky, abyste získali přístup k prostředkům na účtech Dronetag.

Nabízíme dva způsoby ověřování: osobní přístupové tokeny (Personal Access Tokens, PAT) a OpenID Connect. Každý se hodí pro jiné použití, proto si přečtěte, který lépe odpovídá vašemu projektu.

Osobní přístupové tokeny (Personal Access Tokens, PAT)​

Pokud chcete pracovat s vlastními daty ze svého účtu Dronetag — například je dodatečně zpracovávat, vytvořit si vlastní nástroj pro příkazovou řádku (CLI) nebo data převádět do jiného softwaru —, nabízíme pro jednoduchý a přímý přístup k API osobní přístupové tokeny (PAT).

Tyto tokeny jsou snadno použitelné, ale méně bezpečné. Pro robustnější integrace určené veřejnosti doporučujeme spíše OpenID Connect.

Vytvoření nového tokenu​

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

Nově vydaný osobní přístupový token si bezpečně uložte. Znovu ho už zobrazit nepůjde.

Autorizace požadavků tokenem​

Token nyní můžete při požadavcích posílat v HTTP hlavičce X-Personal-Access-Token.

Příklad požadavku s PAT​

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

Implementace OpenID Connect​

Když implementujete přihlášení Sign in with Dronetag, umožníte uživatelům přistupovat k jejich datům přes vaši aplikaci. Tento způsob je spolehlivější a nabízí standardizovaný přístup k ověřování.

Co je OpenID Connect (OIDC)​

Naše implementace vychází z OpenID Connect (nezaměňujte s OpenID). Díky OIDC můžete využít existující knihovny a vaše aplikace ho možná už podporuje. Více se dozvíte na webu OpenID Foundation.

Abyste mohli OIDC ve své aplikaci použít, potřebujete vlastní client ID a secret. Pokud jste tyto přihlašovací údaje ještě nedostali, kontaktujte nás.

Implementace ověřování ve vaší aplikaci​

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"
}

Tabulka výše předpokládá, že vaše aplikace už má přidělené „Client ID“ a „Client Secret“. Pro testování můžete použít obecné Client ID dronetag-integration-test, ke kterému secret není potřeba. Pro produkční provoz musí mít každá aplikace vlastní jedinečné Client ID, jinak může být omezen objem stahovaných dat. Přihlašovací údaje vám vydá podpora Dronetagu.

Použití přístupových tokenů​

Osobní přístupové tokeny i přístupové tokeny získané přes OIDC můžete k ověření požadavků na API posílat jako Bearer token v hlavičce Authorization.

Příklad požadavku​

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

Obnovování tokenů​

Přístupové tokeny vydávané jako JWT mají krátkou platnost a po vypršení je nutné je obnovit. Více o obnovovacích tokenech (refresh token) a jejich bezpečném používání najdete v těchto zdrojích (anglicky):

• 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