Getting started
Getting Started
The SafeSky API is accessible via a standard REST API, enabling seamless integration with your applications. To start using the API:
-
Get an API Key:
Visit SafeSky and subscribe to the desired plan. -
Make API Calls:
Use the endpoints provided, including the appropriate parameters in your requests. All responses are returned in JSON format. -
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.
Model Definition
1. UAV Model
The UAV model represents the structure and attributes of an Unmanned Aerial Vehicle (UAV) as captured in the SafeSky system.
| Field | Type | Required | Description | Constraints |
|---|---|---|---|---|
id |
string |
Yes | The unique identifier of the UAV. | Max length: 15 characters |
latitude |
double |
Yes | Latitude in decimal degrees. | Range: -90 to 90 |
longitude |
double |
Yes | Longitude in decimal degrees. | Range: -180 to 180 |
altitude |
int |
Yes | Height of the UAV in meters, based on GPS altitude AMSL. | |
altitudeAccuracy |
int |
No | Accuracy level of the altitude coordinate in meters. | |
accuracy |
int |
No | Accuracy level of the latitude and longitude coordinates in meters. | |
callSign |
string |
No | UAV call-sign. | |
groundSpeed |
int |
No | Current ground speed of the UAV, specified in meters per second. | |
course |
int |
No | Direction of travel, specified in degrees counting clockwise relative to the true north. | |
status |
string |
No | The current status of the UAV. Allowable values: INACTIVE, AIRBORNE, GROUNDED. |
|
lastUpdate |
long |
Yes | The time of the event in seconds since epoch at UTC-0. | |
turnRate |
float |
No | Turn rate in degrees per second. | |
verticalRate |
int |
No | Vertical rate in meters per second. A positive value indicates climbing, a negative value indicates descent. |
2. Beacon Model
The Beacon model defines the structure of an aircraft beacon, including its attributes and behavior.
| Field | Type | Required | Description | Constraints |
|---|---|---|---|---|
id |
string |
Yes | The unique identifier of the beacon. | |
latitude |
double |
Yes | Latitude in decimal degrees. | |
longitude |
double |
Yes | Longitude in decimal degrees. | |
altitude |
int |
Yes | Height of the beacon in meters, based on GPS altitude AMSL. | |
altitudeAccuracy |
int |
No | Accuracy level of the altitude coordinate in meters. | |
accuracy |
int |
No | Accuracy level of the latitude and longitude coordinates in meters. | |
callSign |
string |
No | Beacon call-sign, available only if the pilot has a public profile. | |
groundSpeed |
int |
Yes | Current ground speed of the beacon, specified in meters per second. | |
course |
int |
Yes | Direction of travel, specified in degrees counting clockwise relative to the true north. | |
status |
string |
No | The current status of the beacon. Allowable values: INACTIVE, AIRBORNE, GROUNDED. |
|
lastUpdate |
long |
Yes | The time of the event in seconds since epoch at UTC-0. | |
turnRate |
float |
No | Turn rate in degrees per second. | |
verticalRate |
int |
No | Vertical rate in meters per second. A positive value indicates climbing, a negative value indicates descent. | |
beaconType |
string |
No | The type of the beacon. Allowable values: UNKNOWN, GLIDER, PARA_GLIDER, HAND_GLIDER, HELICOPTER, UAV, etc. |
|
transponderType |
string |
No | The type of transponder broadcasting the position. Allowable values: ADS-BI, FLARM, ADS-B, etc. |
Endpoints Overview
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 10,000 meters, with a maximum of 20,000 meters.
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: 20,000 meters). | 10,000 |
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.
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.
Support
For assistance or further inquiries, please contact us at support@safesky.app or visit our website.
Disclaimer
SafeSky is a non-certified eConspicuity platform that collects and shares information provided by a voluntary and unstructured community of pilots and ground stations. Therefore, no data accuracy, comprehensiveness, nor permanent transmission can be guaranteed while using the API.
The main purpose of the software is to remind and support everybody’s personal duty to ‘See, Be Seen and Avoid’ when flying, i.e., to look out at all times.
Hence, SafeSky can in no way be held liable for any event happening during the flight.
While SafeSky provides significantly more flight traffic information than a single system or no system at all, it will not show everything. Visibility can be affected by factors like pilots not using a detection device, limited ground station coverage, poor internet, or poor GPS quality.
Before using this API, you must have read and agreed to the Terms And Conditions.