Skip to main content

Advisory UAV operations

Here is the updated documentation with a clear distinction between publishing a polygon and publishing a point with a radius in the advisory API.

Advisory UAV Operations

The SafeSky API enables the management of advisory information for UAV operations, allowing for the publication of UAV activity areas and retrieval of active advisories within specified parameters.

The SafeSky API utilizes GeoJSON, a widely adopted format for encoding geographic data structures. GeoJSON allows UAV operators to define activity areas using points, lines, polygons, and multi-geometries, making it an ideal standard for representing advisory areas in aviation. To learn more about GeoJSON and its structure, visit the Wikipedia page on GeoJSON.

1. Publish Advisory Information

Endpoint: POST /v1/advisory

Description: Publish one or more UAV activity areas to the SafeSky platform.

Request Headers:

  • Content-Type: application/json
  • x-api-key: <your_api_key>

Request Body:

The request body should be a GeoJSON structure containing one or many advisory areas. The advisory area can be represented using either a polygon or a point with a radius.

Publishing a Polygon Advisory

The advisory defines an area of UAV activity using a polygon with specific properties.

GeoJSON Example:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "id": "Advisory123",
        "call_sign": "UAV_Alpha",
        "last_update": 1738142598,
        "max_altitude": 150,
        "remarks": "Surveying area"
      },
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [4.39201, 50.69378],
            [4.39300, 50.69400],
            [4.39400, 50.69500],
            [4.39201, 50.69378]
          ]
        ]
      }
    }
  ]
}

Publishing a Point Advisory with a Radius

Instead of a polygon, a point can be used to represent a UAV operation with a maximum radius.

GeoJSON Example:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "id": "my_advisory_id2",
        "max_altitude": 150,
        "max_distance": 500,
        "last_update": 1738142598,
        "call_sign": "Advisory test with a point",
        "remarks": "Inspection rails"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          4.4,
          50.7
        ]
      }
    }
  ]
}

{ "type": "FeatureCollection", "features": [ { "type": "Feature", "properties": { "id": "my_advisory_id1", "max_altitude": 111, "last_update": {{$timestamp}}, "call_sign": "Advisory test with polygon", "remarks": "Inspection powerlines" }, "geometry": { "type": "Polygon", "coordinates": [ [ [4.3948, 50.6831], [4.3952, 50.6832], [4.3958, 50.6835], [4.3963, 50.6838], [4.4072, 50.6902], [4.4075, 50.6903], [4.4081, 50.6905], [4.4085, 50.6907], [4.4092, 50.6910], [4.4096, 50.6912], [4.4103, 50.6915], [4.4106, 50.6917], [4.4110, 50.6920], [4.4113, 50.6922], [4.4116, 50.6925], [4.4118, 50.6927], [4.4120, 50.6930], [4.4121, 50.6932], [4.4120, 50.6935], [4.4118, 50.6937], [4.4115, 50.6940], [4.3750, 50.7150], [4.3748, 50.7153], [4.3746, 50.7155], [4.3742, 50.7158], [4.3740, 50.7160], [4.3735, 50.7162], [4.3733, 50.7163], [4.3435, 50.7280], [4.3432, 50.7281], [4.3426, 50.7283], [4.3423, 50.7284], [4.3416, 50.7286], [4.3412, 50.7287], [4.3405, 50.7288], [4.3402, 50.7289], [4.3395, 50.7290], [4.3392, 50.7290], [4.3385, 50.7291], [4.3382, 50.7291], [4.3376, 50.7290], [4.3373, 50.7289], [4.3367, 50.7287], [4.3365, 50.7286], [4.3360, 50.7284], [4.3358, 50.7282], [4.3200, 50.7210], [4.3195, 50.7208], [4.3193, 50.7207], [4.3189, 50.7205], [4.3187, 50.7203], [4.3185, 50.7200], [4.3184, 50.7198], [4.3182, 50.7195], [4.3181, 50.7193], [4.3948, 50.6831] ] ] } }, { "type": "Feature", "properties": { "id": "my_advisory_id2", "max_altitude": 150, "max_distance": 500, "last_update": {{$timestamp}}, "call_sign": "Advisory test with a point", "remarks": "Inspection rails" }, "geometry": { "type": "Point", "coordinates": [ 4.4, 50.7 ] } } ] }

Required Properties in GeoJSON

Each advisory must include the following properties:

Parameter Type Required Description
id string Yes A unique identifier for the advisory message. This helps in tracking and managing advisories.
call_sign string No The call sign associated with the UAV operation. It can be used for easy identification.
last_update long Yes The timestamp of the last update in seconds since epoch (UTC-0), ensuring the advisory's relevance.
max_altitude int Yes The maximum altitude (in meters AMSL) at which UAV operations are expected to take place.
remarks string No Free text comments providing additional information about the advisory (e.g., purpose of operation).
max_distance int Yes (for Point) The radius (in meters) defining the UAV operation area when using a point advisory.

Response:

  • 201 Created: Advisory information published successfully.
  • 400 Bad Request: Invalid parameters or failed authentication.

Example Response:

{
  "status": "success",
  "message": "Advisory information published successfully."
}

Notes:

  • Ensure that the coordinates for a polygon form a closed loop by repeating the first coordinate at the end of the array.
  • When using a point, the max_distance property is required to define the radius of operation.
  • The last_update timestamp must be in seconds since epoch (UTC-0).

2. Retrieve Active Advisories

Endpoint: GET /v1/advisory

Description: Retrieve a list of active advisories within a specified viewport and altitude range.

Request Headers:

  • x-api-key: <your_api_key>

Query Parameters:

Parameter Type Required Description Default
viewport string Yes Bounding box for retrieving advisories, formatted as southwest_lat,southwest_lng,northeast_lat,northeast_lng. N/A
altitude_min int No Filter advisories below the given altitude in AMSL meters. Zero means 'unused'. 0
altitude_max int No Filter advisories above the given altitude in AMSL meters. Zero means 'unused'. 0

Example Request:

GET /v1/advisory?viewport=43.1035,-2.0821,47.9943,15.3216&altitude_min=100&altitude_max=500
x-api-key: your_api_key

Example Response:

[
  {
    "id": "Advisory123",
    "call_sign": "UAV_Alpha",
    "aircraft_type": "Quadcopter",
    "last_update": 1738142598,
    "latitude": 50.69378,
    "longitude": 4.39201,
    "max_altitude": 150,
    "remarks": "Surveying area",
    "operationArea": {
      "type": "Polygon",
      "coordinates": [
        [
          [4.39201, 50.69378],
          [4.39300, 50.69400],
          [4.39400, 50.69500],
          [4.39201, 50.69378]
        ]
      ]
    }
  },
  {
    "id": "my_advisory_id2",
    "call_sign": "Advisory test with a point",
    "last_update": 1738142598,
    "latitude": 50.7,
    "longitude": 4.4,
    "max_altitude": 150,
    "remarks": "Inspection rails",
    "operationArea": {
      "type": "Point",
      "coordinates": [4.4, 50.7],
      "radius": 500
    }
  }
]

Response Codes:

  • 200 OK: Returns a list of active advisories.
  • 400 Bad Request: Invalid parameters or authentication failure.

Summary

  • Polygon-based advisories define an operational area using multiple geographic points.
  • Point-based advisories define an operational area using a central point and a radius (max_distance).
  • The viewport parameter is used to filter advisories in a specific geographical area.
  • Altitude filters help narrow advisories to specific height ranges.

This structured documentation ensures that SafeSky UAV operators can publish and retrieve advisory messages efficiently, promoting better airspace awareness and safety. 🚁

Back to top