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.

1.1 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]
          ]
        ]
      }
    }
  ]
}

---

1.2 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
        ]
      }
    }
  ]
}

---

1.3 Publishing Multiple Advisories Simultaneously

You can submit multiple advisories in a single request by including multiple features within the FeatureCollection. These features can be a mix of points (with a defined radius) and polygons, depending on how the advisory areas are represented. This approach allows efficient submission of multiple UAV advisories in a batch format instead of individual POST.

GeoJSON Example: The following example demonstrates how to publish:

• A polygon-based advisory representing an inspection area.
• A point-based advisory with a specified radius.

{
  "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.39201, 50.69378],
            [4.39300, 50.69400],
            [4.39400, 50.69500],
            [4.39201, 50.69378]
          ]
        ]
      }
    },
    {
      "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. 🚁