❗️

Please note that this service does not provide strategic separation

If you would like to submit flight plans that are strategically separated, please use the "Conflict Resolution (Strategic)" API.

Introduction

Flight Reports offer a mechanism to notify other parties about your planned - or in progress - operation of a drone in a particular area, at a particular time for the purposes of greater aerial safety.

Broadly speaking, a Flight Report consists of:

• An Altitude Angel assigned unique flight reference number
• The planned start and end dates and times of the flight
• A programmatic description of the area in which the flight will be carried-out
• An optional public description of the operation, for example, "Chimney survey"
• A declaration as to whether the operation is commercial, or recreational

Where do Flight Reports end up?

Data from Flight Reports is distributed to:

• Consumers of our Flight Reports API
• In all of our first-party products, including our web map, embeddable maps and iOS + Android apps
• In partner solutions developed by 3rd parties using the Altitude Angel APIs
• In situation reports generated from the Tower API
• In some manned aviation flight briefing software

What about privacy?

The primary objective of sharing a Flight Report is to notify other stakeholders of your intent to operate a drone in the specified area. No personally-identifiable information will be given to consumers of this data, however, we do provide a secure mechanism for 3rd parties to send a message to Altitude Angel (which we shall then privately relay to you) should the 3rd party express concern about your operation either prior to its commencement, or during. In this way, we can safeguard your personal information while increasing everyone's overall situation awareness, which contributes to safer skies for everyone.

🚧

Authentication

The Flight Report endpoint creates and tracks flight reports against a known Altitude Angel user. As such it requires a bearer token. Learn more about authentication.

flightReport

Let's get started by creating a simple flight report:

PUT https://api.altitudeangel.com/flightreport HTTP/1.1
Host: api.altitudeangel.com
Authorization: Bearer [USER_BEARER_TOKEN]
Content-Type: application/json

{
    "name": "Example Flight name",
    "desc": "Example Description",
    "flight_type": "rec",
    "timezone": "Europe/Dublin",
    "loc": {
        "Lat": 57.592798333333334,
        "Lng": -2.9976599999999998
    },
    "radius_meters": 500
}

Area of Operation
You'll note that in this example, we are declaring a centre point (taken to be your planned take-off point) and a radius (specified in metres). This is the simplest type of Flight Report to create (and is, in many countries where flights must be conducted within Visual Line-of-Sight rules, the minimum level of detail required to notify nearby operators of your operation).

Time of Operation
Checking the sample request above, you'll see we have omitted a start and end time. That's because the service defaults to a start time of now with an end time 60 minutes from now, which is typically enough for the majority of VLOS drone operations that are being reported 'in the field', i.e. at the time of take-off. You can override these defaults to create shorter or longer Flight Reports by adding start and end time properties on the request object.

Request Object Details

In the body of the request, the object expects the following fields:

Response Object

In response to a valid request, you'll receive the globally unique Altitude Angel identifier for this Flight Report. You should keep this so that you can perform additional actions against the Flight Report later if required.

{
  "flightId": "4fc8cfd8-880c-46b7-9be0-28f40a52ff79",
  "alertId": "89d3f960-9b89-444f-8891-e0ff540f45f6"
}

flightReport/{flightId}

This effectively 'cancels' a Flight Report that you have filed. As Flight Reports are atomic, it is never actually deleted, but it is immediately withdrawn from all public use and retained only within the account of the user who created it.

Note: the service will return a BAD REQUEST if you try to delete a Flight Report that finishes in the past.

Configure Airspace Alerts (optional)

Optionally, it is possible to declare a Flight Report and request push notifications from Altitude Angel about any manned aviation traffic that we detect heading towards the centre of the notified area between the start and end times specified.

This complex operation takes place server-side, and is typically capable of spotting manned aviation traffic carrying a compatible transponder. For more information about Airspace Alerts, please see the Airspace Alerts documentation.

📘

Learn more about Airspace Alerts before activating them

We recommend that you take the time to familiarise yourself with the service characteristics and limitations before implementing them. Like all companies who are dependent on data feeds from the manned aviation community, we recognise that these data are not fully complete and are subject to certain physical and operational limitations.

Let's get started...

flightReport (with Airspace Alert)

In this scenario, we want to create a Flight Report identical to the first example, but with active Airspace Alerts configured over the notified area. To do this, we must add an alert object as a property along with our initial request. This property defines the real-time alert which is to be set-up alongside the Flight Report.

The alert object

Let's take a closer look at the alert object:

"alert": {
        "ActivationMinAlt": {
            "Datum": "Wgs84",
            "Meters": 6.0
        },
        "ActivationMaxAlt": {
            "Datum": "Wgs84",
            "Meters": 806.0
        },
        "AlertDefinition": {
            "SubscriptionTypes": [
                "AircraftLocation"
            ],
            "Actions": [
                {
                    "HookName": "AANotifications",
                    "ClientId": "__YourClientId__"
                }
            ]
        }
    }

As you can see, alerts are fairly straightforward objects even though they enable some very sophisticated monitoring on the server-side.

Properties

ActivationMaxAlt and ActivationMinAlt
These properties specify the upper/lower altitudes that manned aviation must be operating within (or that we calculate will fall within by the time it is over the notified area) before we will send you the alert. A typical alert adds 500 metres to the ground level at the location of take-off.

❗️

A note about altitudes

It's important to include the ground level in your altitude specifications. For example, if you are interested in monitoring aircraft that fly below 500 metres, you must take into account the ground level at the location you have asked us to monitor, and add this to your minimum altitude.

We currently do not automatically adjust for ground level at your location but are adding this feature shortly.

AlertDefinition
This property specifies how the notifications will be sent and what types of notification you would like to receive. Currently AircraftLocation is the only available option, however 'NOTAM' and 'WEATHER' are shortly due to be released into the API for public use (if you would like to beta test, let us know!).

🚧

Setup your webhook URL prior to activating an Airspace Alert

Notifications are sent via webhook to a URL that you specify which we will associate with your unique ClientID. You'll need to contact us to have this added with a straightforward email to [email protected] until we've added the functionality to set this up yourself in our developer portal.

Here's a complete example showing a request to create a Flight Report with an Airspace Alert configured over the area:

PUT https://api.altitudeangel.com/flightreport HTTP/1.1
Host: api.altitudeangel.com
Authorization: Bearer __UserBearerToken__
Content-Type: application/json

{
    "name": "Example Flight Report Name",
    "desc": "Example Flight Report Name",
    "flight_type": "rec",
    "timezone": "Europe/Dublin",
    "loc": {
        "Lat": 57.592798333333334,
        "Lng": -2.9976599999999998
    },
    "radius_meters": 5000,
    "alert": {
        "ActivationMinAlt": {
            "Datum": "Wgs84",
            "Meters": 6.0
        },
        "ActivationMaxAlt": {
            "Datum": "Wgs84",
            "Meters": 806.0
        },
        "AlertDefinition": {
            "SubscriptionTypes": [
                "AircraftLocation"
            ],
            "Actions": [
                {
                    "HookName": "AANotifications",
                    "ClientId": "__YourClientId__"
                }
            ]
        }
    }
}

Receiving Alerts

Altitude Angel will POST a subscription object to your nominated endpoint each time an aircraft matches the filters you have set, provided that aircraft meets other criteria we monitor for. For example, we will omit aircraft that originate within your operating area and are headed away from your centre point by default.

For multi-tenant implementations, the subscription object will contain the Altitude Angel User ID of the user for whom the subscription was established so that you can correlate these within your implementation.

On the top level of the object, the location and altitude of the aircraft are specified. Further information can be found in the triggerMessage property. Of particular interest should be the 'sendRecommendation' and 'closestPoint' property/object. These define whether we recommend that you send this notification on to the end-user and how close we predict the aircraft will come to the notified location, along with an estimated ETA for arrival at that point.

Examples of Alerts

The service will send two types of messages in the property 'notificationType'. These are used to inform you of the status of the alert or items which have triggered an alert.

Service Notification

• SubscriptionStarted
• SubscriptionExpired
• SubscriptionDeactivated
• SubscriptionDeleted

Alerts

• Aircraft

Example Service Notification

{
  "notificationType": "SubscriptionDeleted",
  "subscription": {
    "name": "Testing Alert",
    "id": "eaf610bd-f010-4d57-89e3-fc881e001a57",
    "userId": "2812883ab24b4bbe983a6e1ff1318885",
    "clientId": "YourClientID",
    "activeFromUtc": "2017-01-20T10:38:11.2141836+00:00",
    "activeToUtc": "2017-01-20T11:38:11.2141836+00:00",
    "center": {
      "type": "Point",
      "coordinates": [
        -118.42464290388796,
        33.950450712344889
      ]
    }
  }

Example Aircraft Notification

{
  "notificationType": "Aircraft",
  "subscription": {
    "name": "Testing Alert",
    "id": "eaf610bd-f010-4d57-89e3-fc881e001a57",
    "userId": "2812883ab24b4bbe983a6e1ff1318885",
    "clientId": "YouClientId",
    "activeFromUtc": "2017-01-20T10:38:11.2141836+00:00",
    "activeToUtc": "2017-01-20T11:38:11.2141836+00:00",
    "center": {
      "type": "Point",
      "coordinates": [
        -118.42464290388796,
        33.950450712344889
      ]
    }
  },
  "trigger": {
    "triggerName": "ABW541",
    "location": {
      "lat": 33.94029,
      "lng": -118.354
    },
    "triggeredAt": "2017-01-20T10:50:16.9016901Z"
  },
  "message": {
    "hasSpeed": true,
    "name": "ABW541",
    "speedOverGroundKnots": 167.0,
    "hasAltitude": true,
    "altitudeAgl": {
      "datum": "Agl",
      "meters": 207.35999317248022
    },
    "altitudeAmsl": {
      "datum": "Msl",
      "meters": 213.35999317248022
    },
    "distanceFromObserver": 6640.6808845036685,
    "aircraftHeading": 264.0,
    "isFastMoving": false,
    "hasHeading": true,
    "hasPredictedCourse": true,
    "compassPointToAircraft": 2,
    "reportGenerationTime": "2017-01-20T10:50:17.059764Z",
    "closestPoint": {
      "distanceFromObserver": 1799.5990688170771,
      "secondsUntilArrival": 58,
      "point": {
        "lat": 33.934244942995285,
        "lng": -118.4227724036105
      },
      "arrivalTimeLocal": "2017-01-20T10:51:16Z",
      "flyingAwayFromObserver": false,
      "willPassWithinOneMile": false,
      "compassPointOfAircraftHeading": 4,
      "compassPointToClosestPoint": 3
    },
    "sendRecommendation": {
      "reasonCode": 6,
      "shouldSendAlert": true,
      "reasonString": "Notifying.NoPreviousAlert"
    },
    "isUpdateMessage": false
  }
}

Flight Report Request Validation Rules

Basic Fields

1. Name:

   • Required to be non-empty and only contain alphanumeric characters and spaces.

2. Description (Optional):

   • Required to be non-empty and only contain alphanumeric characters and spaces.

Time Constraints

1. Start Time: Must not be excessively historical, specifically no more than 5 minutes before the current time.
2. End Time: If given, the interval from the start time must not surpass the maximum flight length of 24 hours.

Location and Radius

1. Location:

   • Cannot be null and:
     • Latitude: Must be a valid number within ±90 degrees.
     • Longitude: Must be a valid number within ±180 degrees.

2. RadiusMeters:

   • Must be positive and not exceed the maximum radius of 5000 meters.

Airspace Alert Validation (optional)

1. Name: Required to be non-empty and only contain alphanumeric characters and spaces.
2. Timezone: Required to be specified in IANA TZ Db format e.g. Europe/London.
3. Traversal Center:
   • Cannot be null and:
     • Latitude: Must be a valid number within ±90 degrees.
     • Longitude: Must be a valid number within ±180 degrees.
4. Traversal Radius Meters:
   • Must be positive and not exceed the maximum radius of 5000 meters.
5. Alert Definition:
   • Must be provided, including at least one action and one subscription type - currently only AircraftLocation is supported.
   • Altitude limits must be defined and fall in range of 50 to 1500 meters of altitude separation.
6. Activation Period:
   • Must have a valid start and end time, the end time must be later than the start time.