The Altitude Angel Developer Hub

Welcome to the Altitude Angel developer hub. You'll find comprehensive guides and documentation to help you start working with Altitude Angel as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Flight Reports

The flight report endpoint allows you to create an entry on the map to notify others of a flight and optionally creation of a real time airspace alert.

❗️

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:

PropertyDescription
nameThe name of the flight (visible publicly)
descThe description of the flight (visible publicly)
flight_type"rec" or "com" to specify whether the flight is commercial or recreational
timezoneThe timezone of the start and end times of the flight, as referenced in the IANA timezone database ([https://en.wikipedia.org/wiki/List_of_tz_database_time_zones](IANA Timezone Database))
locObject specifying the Lat and Lng of the flight
radius_metersThe radius around the location in which you'll be operating. Eg. 500m
startOptional. Defaults to now. The planned start time (in the format YYYY-MM-DDTHH:mm:ss) for the operation you are declaring.
endOptional (unless you have specified a start, in which case Required). Defaults to 60 minutes from now if no start is specified. (Also using the format YYYY-MM-DDTHH:mm:ss)

📘

Flight Reports cannot overlap

You will not be permitted to create any Flight Report that begins within the start or end time of another active Flight Report. This will result in a 400 - BAD REQUEST.

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"
}
PropertyDescription
flightIdThe unique ID of this Flight Report
alertId[optional] The ID of any real-time alert that we have setup, if you have requested this.

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

Updated 23 days ago


What's Next

Please fully familiarise yourself with the operational characteristics and limitations of Airspace Alerts before enabling them and remember that the use of the Airspace Alerts feature is subject to additional terms and conditions that include a requirement for you to notify your end-users of the same operational characteristics and limitations.

Airspace Alerts

Flight Reports


The flight report endpoint allows you to create an entry on the map to notify others of a flight and optionally creation of a real time airspace alert.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.