Skip to main content

API definition

The SafeSky API is accessible via a standard REST API, enabling seamless integration with your applications. To start using the API:

  1. Get an API Key:
    Visit SafeSky and subscribe to the desired plan.

  2. Make API Calls:
    Use the endpoints provided, including the appropriate parameters in your requests. All responses are returned in JSON format.

  3. Authentication:
    Authentication is automatically managed when making requests with your API key.
    Important: Never disclose your API key and take all necessary security measures to protect it.

Endpoints Overview

SafeSky provides two API endpoints for different purposes: Sandbox and Production. Each endpoint requires a separate API key, which ensures appropriate access levels for testing and live environments.

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.

  • Endpoint URL: https://sandbox-public-api.safesky.app

  • API Key: You will receive a sandbox-specific API key upon registration. Ensure this key is used exclusively for sandbox testing.

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.

  • Usage Guidelines:

    • Ensure robust error handling and retry mechanisms in your application.
    • Follow the recommended request limits to avoid throttling.

  • Endpoint URL: https://public-api.safesky.app

  • API Key: A production-specific API key is required. This key must not be shared and should be stored securely following best practices (e.g., environment variables or secret management systems).

Aircraft lifecycle and status

SafeSky automatically manages the lifecycle of published aircraft based on the latest traffic timestamp. With multiple data sources, the most recent information is always prioritised for exposed traffic.

Aircraft can have one of three possible statuses: GROUNDED, AIRBORNE, or INACTIVE. If an aircraft stops transmitting its position, the last known position will continue to be provided with an INACTIVE status for up to 30 seconds. After this period, the aircraft will no longer be visible.

1. Get Nearby Aircraft

Endpoint: GET /uav
Description: Retrieve a list of airborne aircraft within a specific radius and altitude range from the given latitude and longitude. By default, the search radius is 10000 meters, with a maximum of 20000 meters.

Note: If you have published UAvs to the API, they will be part of the response.

Query Parameters:

Parameter Type Required Description Default
lat double Yes Latitude in decimal degrees (4 decimal precision). N/A
lng double Yes Longitude in decimal degrees (4 decimal precision). N/A
alt_min int No Filter all aircraft below the given altitude in meters. Zero means 'unused'. 0
alt_max int No Filter all aircraft above the given altitude in meters. Zero means 'unused'. 0
rad int No Radius in meters from the reference point (maximum: 20000 meters). 10000

Response:

  • 200 OK: Returns a list of nearby aircraft.
  • 400 BAD REQUEST: Invalid parameters or failed authentication.

Example Request:

GET /uav?latitude=48.8588&longitude=2.2943&altitude_min=1000&altitude_max=3000&radius=15000

Example Response:

[
     {
        "latitude": 48.86584,
        "longitude": 2.63723,
        "beacon_type": "JET",
        "call_sign": "IBE06CK",
        "transponder_type": "ADS-B",
        "last_update": 1733412793,
        "altitude": 10554,
        "vertical_rate": 2,
        "accuracy": 0,
        "altitude_accuracy": 0,
        "course": 205,
        "ground_speed": 237,
        "turn_rate": 0.0,
        "status": "AIRBORNE",
        "id": "3423C3"
    },
    {
        "latitude": 48.95459,
        "longitude": 2.44153,
        "beacon_type": "JET",
        "call_sign": "NJE419F",
        "transponder_type": "ADS-B",
        "last_update": 1733412793,
        "altitude": 0,
        "vertical_rate": 0,
        "accuracy": 0,
        "altitude_accuracy": 0,
        "course": 292,
        "ground_speed": 0,
        "turn_rate": 0.0,
        "status": "GROUNDED",
        "id": "494105"
    }
]

2. Publish UAV and Get Nearby Aircraft

Endpoint: POST /uav
Description:Publishes one or many UAV position to the SafeSky platform. Optionally, it's returning a list of nearby aircraft for each UAV position within a radius of 10000 meters. This response will not include the UAV you have posted.

Note: UAVs that you have published are excluded from the response.

Request Body:

Field Type Required Description
id string Yes Unique identifier for the UAV.
latitude double Yes Latitude in decimal degrees (4 decimal precision).
longitude double Yes Longitude in decimal degrees (4 decimal precision).
altitude int Yes Altitude of the UAV in meters.
groundSpeed int Yes Ground speed of the UAV in meters per second.
course int Yes Direction of travel in degrees clockwise relative to true north.
status string Yes Current status of the UAV (INACTIVE, AIRBORNE, GROUNDED).

Query Parameters:

Parameter Type Required Description Default
alt_min int No Filter all aircraft below the given altitude in meters. Zero means 'unused'. 0
alt_max int No Filter all aircraft above the given altitude in meters. Zero means 'unused'. 0
return_nearby_traffic boolean No Return information about aircraft traffic within proximity of the UAV positions. false

Additional query Parameters when show_nearby_traffic = true:

Parameter Type Required Description Default
rad int No Radius distance in meters from all UAV reference point (maximum: 20000 meters). 10000
return_grounded_traffic boolean No Include grounded beacons. false

Response:

  • 201 CREATED: UAV published successfully; returns a list of nearby aircraft.
  • 400 BAD REQUEST: Invalid parameters or failed authentication.

Example POST Request:

POST /uav?altitude_min=1000&altitude_max=3000&radius=15000
Content-Type: application/json

[
    {
        "id": "UAV123",
        "status": "AIRBORNE",
        "altitude": 180,
        "course": 250,
        "ground_speed": 24,
        "latitude": 50.69378,
        "longitude": 4.39201,
        "call_sign": "FlyingFrog"
    }
]

Similar response as Get Nearby Aircraft will be returned.

3. Check for API health

Endpoint: GET /
Description:
Provides health checks against the API. Returns the string 'UP' if network services are up and running.

Support

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

Back to top