Skip to main content

Overview

Introduction

The SafeSky UAV API offers a comprehensive solution for drone operators and manufacturers to enhance situational awareness by managing two distinct types of drone traffic data:

  1. Live UAV Operations: "/v1/uav"

This API allows to publish real-time telemetry data of drones, including position, altitude, and velocity. By publishing live traffic, drones become visible within the SafeSky network, promoting safer integration with other airspace users.

The typical approach is to PUSH one or multiple live traffic data in a batch. In response, the system returns traffic in the vicinity of all UAVs within a default radius. This method is the most efficient way to avoid polling unnecessary traffic, ensuring optimal performance.

  1. Advisory UAV Operations: "/v1/advisory"

For data sources that don't provide live telemetry, the API allows the submission of advisory messages to define active drone operations using polygons or circles, along with a maximum altitude. This ensures that ongoing drone activities are visible within the SafeSky network, even when real-time telemetry data isn't available.

API Gateway & Endpoint

All API traffic is routed through a single gateway endpoint:

  • API Gateway URL: https://uav-api.safesky.app

Your API key determines the environment your requests are routed to. Each API key is associated with either a sandbox or production environment. The gateway automatically routes your request to the correct backend based on the environment configured for your API key.

Important: You do not need to change the endpoint URL between sandbox and production. Simply use the appropriate API key, and the gateway handles the routing automatically.

Sandbox

The sandbox environment is designed for development and integration testing. It allows you to test API calls and functionalities without affecting the live production data.

  • Key Features:

    • Simplified environment with limited traffic data.
    • Ideal for debugging, testing payloads, and verifying integration.
    • No quota enforcement or usage metering, sandbox API keys are exempt from billing.
    • Data quality is marked as degraded (test data).

  • API Key: You will receive a sandbox-specific API key upon registration. This key is configured with environment: sandbox and will automatically route your requests to the sandbox backend.

Sandbox traffic can be monitored here: https://sandbox-live.safesky.app/

Production

The production environment is the live SafeSky API, providing real-time and unfiltered access to traffic data. This environment is intended for operational use and live deployments.

  • Key Features:

    • Access to all real-time traffic data, including manned and unmanned aircraft.
    • Supports high-availability operations with optimized performance for production workloads.
    • Full quota enforcement and usage metering apply.

  • Usage Guidelines:

    • Ensure robust error handling and retry mechanisms in your application.
    • Follow the rate limits described below to avoid throttling.

  • API Key: A production-specific API key is required. This key is configured with environment: production and will automatically route your requests to the production backend. This key must not be shared and should be stored securely following best practices (e.g., environment variables or secret management systems).

Live traffic can be monitored here: https://live.safesky.app/

Altitude Reference Model

Altitude can be expressed against several different reference surfaces, and a value in metres or feet is meaningless without knowing which reference it uses. The SafeSky API standardises on a single, well-defined model so that integrators can publish and consume altitude data without ambiguity.

Reference surface

All altitudes exchanged through the SafeSky UAV API are AMSL (Above Mean Sea Level) values, expressed in metres, referenced to the EGM96 geoid.

Property Value
Reference Mean Sea Level (AMSL)
Geoid model EGM96 (Earth Gravitational Model 1996)
Unit metres
Grid resolution 0.25° × 0.25°
Interpolation Bicubic spline (bilinear near poles)
Typical accuracy ≈ 1–2 m (model + interpolation)

Why this matters: "AMSL" is not a single fixed surface. The actual height of mean sea level varies with the geoid model used (EGM96, EGM2008, national geoids, local vertical datums). Differences between models can reach 20–50 m in some regions. SafeSky uses EGM96 consistently across every backend service, every ingestion source, and every API response.

What you should send

When publishing telemetry on /v1/uav, set the altitude field as follows:

Source of altitude on your device Conversion required before publishing
GNSS geometric altitude (WGS84 ellipsoid) Yes — subtract the EGM96 undulation N at the drone's lat/lon: AMSL = h_WGS84 − N(lat, lon)
Barometric (1013.25 hPa pressure altitude) Yes — correct for local QNH; result is an approximation of EGM96-AMSL
Already AMSL/EGM96 (e.g. from an autopilot configured that way) No conversion

Do not publish ellipsoidal altitude as AMSL: this introduces a systematic error of typically −30 m to +85 m depending on location.

What you receive

Traffic returned in the response uses the same convention:

  • altitude — integer metres, AMSL, referenced to EGM96.
  • For sources that originally transmit WGS84 (e.g. ADS-B alt_geom, ADS-L, FLARM), SafeSky performs the EGM96 correction at ingestion.
  • For sources that transmit barometric altitude only (e.g. some ADS-B alt_baro, PilotAware), SafeSky converts to AMSL using the current QNH pressure for the region. These values are an approximation and should be expected to drift by a few tens of metres from a true EGM96 AMSL value.

Advisory operations

For /v1/advisory, the maxAltitude field follows the same convention: metres, AMSL, EGM96. It defines the upper bound of the operating volume in the same reference as live traffic, so vertical separation can be computed consistently.

Notes on other geoid models

SafeSky does not currently expose altitudes in EGM2008 or any national vertical datum. If your operational regulations require reporting against a specific national datum (e.g. NAP, NAVD88, IGN69), you must perform the conversion locally; the EGM96 → national-datum offset is generally well documented by the relevant national geodetic agency.

Rate Limiting & Throttling

The API gateway enforces rate limits to protect backend services and ensure fair usage across all customers. Throttling is applied per source IP address at the network edge.

Limits

Scope Limit Enforced by
Per IP address 6 000 requests per minute Google Cloud Armor (edge)

This limit supports approximately 100 drones updating at 1 request per second from a single IP address. In practice, most deployments will not approach this limit because traffic originates from multiple IP addresses.

Sandbox keys are subject to the same per-IP rate limit, but are exempt from quota enforcement and usage metering.

Throttled response

When the rate limit is exceeded, the gateway returns an HTTP 429 Too Many Requests response. The response body is a minimal HTML page generated at the network edge — it is not a JSON API response:

HTTP/1.1 429 Too Many Requests
Content-Type: text/html

<!doctype html>...429 Too Many Requests
HTTP status Meaning Recommended action
429 Rate limit exceeded Back off and retry after a short delay (e.g. 1–5 seconds). Reduce request frequency if 429s persist.
  • Implement exponential backoff — when receiving a 429, wait an increasing amount of time before retrying (e.g. 1 s, 2 s, 4 s).
  • Distribute load over time — stagger drone update intervals rather than sending all updates simultaneously.
  • Do not retry immediately — rapid retries will continue to be throttled and may extend the throttling window.

Platform Status API

Before building or operating an integration with the SafeSky API, you can programmatically check whether the platform is available.

Status endpoint

GET https://status.safesky.app/api/v1/status

No authentication is required. The endpoint is public and responses are cached at the CDN edge for 60 seconds, matching the platform's check interval.

Response

{
  "status": "operational",
  "checkedAt": "2026-03-16T14:32:01.000Z",
  "services": {
    "app-api": {
      "name": "SafeSky App API",
      "status": "operational",
      "lastCheckedAt": "2026-03-16T14:32:01.000Z"
    },
    "public-api": {
      "name": "SafeSky Public API",
      "status": "operational",
      "lastCheckedAt": "2026-03-16T14:32:01.000Z"
    },
    "adsl-api": {
      "name": "Fly ADSL API",
      "status": "operational",
      "lastCheckedAt": "2026-03-16T14:32:01.000Z"
    },
    "uav-api": {
      "name": "UAV API",
      "status": "operational",
      "lastCheckedAt": "2026-03-16T14:32:01.000Z"
    },
    "collector": {
      "name": "SafeSky Data Aggregation",
      "status": "operational",
      "lastCheckedAt": "2026-03-16T14:32:01.000Z"
    }
  }
}
Top-level status values
Value Meaning
operational All services are functioning normally
degraded One or more services are experiencing intermittent issues
disrupted One or more services are unavailable

Per-service status values follow the same vocabulary: operational, degraded, outage, or unknown (returned only on cold start before the first check cycle completes).

The checkedAt field reflects the timestamp of the most recent completed check cycle. Status is refreshed every 60 seconds.

Human-readable status page

The same status information is available as a dashboard at https://status.safesky.app, showing real-time status, a 24-hour uptime timeline, and incident history for each service.

Integration example

Check platform status before establishing connections or starting a mission:

async function isPlatformAvailable() {
  const res = await fetch("https://status.safesky.app/api/v1/status");
  const { status } = await res.json();
  return status === "operational" || status === "degraded";
}

degraded is treated as available — the platform is reachable but may be slower than usual. Only disrupted should block a safety-critical operation.

Platform status Recommended action
operational Proceed normally
degraded Proceed with caution; show a warning to the operator
disrupted Halt non-essential API calls; alert the operator
Endpoint unreachable Treat as disrupted; do not assume availability

Safety note: The status API reflects availability as observed from SafeSky's own monitoring infrastructure. It does not replace your application's own error handling and retry logic. Always implement robust error handling on API calls regardless of reported platform status.

Support

For assistance or further inquiries, please contact us at support@safesky.app.

Back to top