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    

Map Data

This endpoint returns data in GeoJSON format (see https://tools.ietf.org/html/rfc7946) which is supported by most common mobile and web map controls, and is ideal for anyone wanting to work directly with the data available on our maps. However, if you just want an embeddable version of our map, take a look at our Embeddable Map.

Introduction

Aeronautical data is often complex and isn't comprised of a single source. However, with this service, you simply specify the region you're interested in, and Altitude Angel will return:

  • Aeronautical data pertinent to the operation of a drone, such as airspace classifications where such classifications extend to the surface (SFC);
  • Ground Hazards data from over 70 categories, such as power pylons, land-zone use data such as schools, critical infrastructure and much more;
  • NOTAMs (Temporary Flight Restrictions and Navigation Warnings).

As this data is normalised into GeoJSON, it can often be directly (or very easily) incorporated into your favourite mapping product.

Purpose

This API call essentially combines multiple input data sources into a single output call, to minimise complex processing often associated with computing a detailed air-situation or "total" (comprising land-based and aerial hazards) hazard picture.

For example, for queries describing areas within the United Kingdom, we automatically include parsed NOTAMs (TFRs & Navigation Warnings) within the response, with indications as to whether or not they are active and when they will become active or inactive.

📘

Keep it fresh!

One of our core principles is to always ensure that the data we give you is as up-to-date as it possibly can be. This means that aeronautical data is updated in accordance with the international AIRAC cycle (on a 28-day period), and with a direct connection into the international NOTAM system, NOTAMs appear within seconds of being published by the relevant authority if they match our criteria for inclusion.

❗️

Detail Levels

Shapes with complex borders may be simplified when the requested region is over 100,000 square meters, to keep payload sizes reasonable. Currently this only affects some national parks in the US.

Any shapes affected by this will have "pointCulled" specified as "true" and may have had points removed. Typically this won't affect map display because the fidelity will increase as the requested region is reduced. To receive data without culling, for an affected shape, request an area below 100,000 square meters.

❗️

Anti-cache warning

We recommend against caching calls to/from this service for more than a minute or two at a time, since much of it is derived from real-time sources, such as nearby drone flights and/or information entered into the NOTAM system. From a safety perspective, it is better to work with the latest data.

A note about geometries

This endpoint will return results in GeoJSON format to facilitate the inclusion of this data in mapping products, and the manipulation of this data by a number of off-the-shelf frameworks.

Ensure that code interpreting the response from Altitude Angel can properly handle:

  • Point
  • MultiPoint
  • LineString
  • MultiLineString
  • Polygon
  • MultiPolygon
  • GeometryCollection

Circles

GeoJSON doesn't specify a circle geometry; instead, it approximates a circle using a multi-point polygon. We have found that many of our users would prefer a simple "point + radius" element, so by default, this endpoint will return an additional radius property (specified in metres) on a point geometry where the point is the centre of a circle. Don't forget to add support for processing these as you don't want to miss certain elements.

You can toggle this behaviour 'off' though (and revert to using Polygon approximations of a circle) by specifying isCompact=false as a querystring parameter in your request. Simple!

Request map data for an area

Call this endpoint to request aerial and ground hazard information about a particular area. Many of our users will, for example, implement calls to this service whenever a user scrolls around a map. Because the return type is GeoJSON, it's very easy to incorporate this data into visual user interfaces.

Limits

The airspace data and ground hazard data apply different limits and will not return data if you specify an area that is above these limits. It is always important to check the response from us to verify whether you are not seeing data because there actually isn't any, or (more likely) you're not seeing data because the area you requested was too large, and would have resulted in a very large response.

Data type

Max. Requestable Area (sq. M)

Ground hazards

20,000,000 (~4.5 km by ~4.5 km)

Airspace

10,000,000,000 (100 km x 100 km)

Our endpoints are not designed to display "world" data. For example, if you are displaying this data on a map control, you must be zoomed in to approximately 'city' level in order to see Airspace and Ground Hazards.

Request Details

This endpoint will return data for the area specified by a bounding box, subject to maximum queryable area limits as defined above.

Querystring parameterDescription
nThe north coordinate of the bounding box in degrees
eThe east coordinate of the bounding box in degrees
sThe south coordinate of the bounding box in degrees
wThe west coordinate of the bounding box in degrees

Sample Request

GET https://api.altitudeangel.com/v2/mapdata/geojson?n=51.46227963315035&e=-0.9569686575500782&s=51.450125805383585&w=-0.9857433958618458 HTTP/1.1
Authorization: X-AA-ApiKey YOUR_API_KEY

Response Details

The response conforms to the GeoJSON specification and provides a feature collection
containing the airspace and ground hazards requested. There are several extended fields in our GeoJSON responses to describe
the returned features.

🚧

Displaying the response data

We have optimised the geoJson endpoint to return data ready for display on a graphical user interface. For this reason, we recommend you bind your user interface to the display property which will contain multiple sections describing the item.

The endpoint also returns additional properties for those who wish to work directly with the raw data, however additional properties vary according to the type of item returned.

Top Level Properties

NameTypeDescription
isCompleteDatabooleanTrue indicates the data returned is as requested. False indicates the data is partial, likely caused by a limit restriction
excludedDataobjectDetails any omissions from the returned data or errors

Excluded Data

NameTypeDescription
messagestringA human readable message documenting the reason for the exclusion
detailobjectFurther details on the exclusion
errorReasonstring tokenA standardized token that can be programatically checked

Reason Tokens

NameDescription
QueryAreaTooLargeThe area specified in the query was too large for a particular dataset to be returned. Limits are specified above, in the 'Limits' section.

Custom Feature Properties

NameTypeDescription
fillColorstring colorRecommended color for the shape fill
fillOpacitystring floatRecommended fill opacity value from 0.0 to 1.0
strokeColorstring colorRecommended color for the shape fill
strokeWidthstring intRecommended pixel stroke width for the shape
strokeOpacitystring floatRecommended stroke opacity value from 0.0 to 1.0
detailedCategorystringA hierarchical ':' separated category for the feature
iconUrlstring urlRecommended icon for the feature
namestringThe name of the feature
categorystring tokenThe type of feature this represents
operationalFromstring datetimeThe time the airspace is operational from
operationalTostring datetimeThe time the airspace is operational to
airacobjectAIRAC cycle information for when this feature was updated
filtersobjectRecommended filters that apply to this feature for optional UI display of data
displayobjectRecommends UI display information regarding this feature
actionsobjectRecommended actions for UI interaction for this feature
designatorstringThe Designator for a piece of airspace – note that this property will not be present for all airspace items
airspaceClassstringThe class of the airspace – note that this property will not be present for all airspace items

📘

FAA Facility Map data

FAA Facility Map data is available under the detailedCategory other:altitude_restriction:faa:facility. These items carry additional properties airspaceClass and airportICAOCode.

AIRAC Cycle Information

NameTypeDescription
fromstring dateStart of AIRAC cycle of publication for the feature
tostring dateDate of AIRAC cycle of publication for the feature

Feature Category Tokens

NameDescription
groundHazardA ground hazard
airspaceA region of airspace

Sample Response

{
    "isCompleteData": true,
    "excludedData": [],
    "features": [
        {
            "geometry": {
                "coordinates": [
                    -0.11097720000495453,
                    51.5047321750082
                ],
                "type": "Point"
            },
            "id": "C50B5212F931BE3D6B73B9DF98DFE3A6FAB6D2D6",
            "properties": {
                "fillColor": "#ffbb00",
                "fillOpacity": "0.35",
                "strokeColor": "#b88702",
                "strokeWidth": "1",
                "strokeOpacity": "0.8",
                "detailedCategory": "amenity:kindergarten",
                "iconUrl": "https://www.altitudeangel.com/Map/Icon?icon=amenity_kindergarten.png",
                "name": "St Patrick's Montessori Nursery School",
                "category": "groundHazard",
                "filters": [
                    {
                        "name": "Ground Hazards",
                        "property": "show",
                        "active": true
                    }
                ],
                "display": {
                    "category": "Ground Hazard",
                    "detailedCategory": "amenity kindergarten",
                    "title": "St Patrick's Montessori Nursery School",
                    "sections": [
                        {
                            "iconUrl": "https://www.altitudeangel.com/Map/Icon?icon=amenity_kindergarten.png",
                            "title": "Privacy Concerns",
                            "text": "This classification of area or point is likely to be additionally sensitive to privacy concerns. You may have greater obligations to disclose your intended flight over, within or near these areas to any controlling authority or land owner, particularly if you plan to fly with surveillance equipment."
                        }
                    ],
                    "actions": []
                }
            },
            "type": "Feature"
        },
        {
            "geometry": {
                "coordinates": [
                    [
                        [-0.0999417,51.4964196],[-0.1011906,51.4967419],[-0.1012621,51.496637],[-0.1016399,51.4963695]
                    ]
                ],
                "type": "Polygon"
            },
            "id": "964E61DF803B3EAD2AE0CCEEC7B6D7918AED3896",
            "properties": {
                "fillColor": "#ffbb00",
                "fillOpacity": "0.35",
                "strokeColor": "#b88702",
                "strokeWidth": "1",
                "strokeOpacity": "0.8",
                "detailedCategory": "amenity:university",
                "iconUrl": "https://www.altitudeangel.com/Map/Icon?icon=amenity_university.png",
                "name": "London South Bank University",
                "category": "groundHazard",
                "filters": [
                    {
                        "name": "Ground Hazards",
                        "property": "show",
                        "active": true
                    }
                ],
                "display": {
                    "category": "Ground Hazard",
                    "detailedCategory": "amenity university",
                    "title": "London South Bank University",
                    "sections": [
                        {
                            "iconUrl": "https://www.altitudeangel.com/Map/Icon?icon=amenity_university.png",
                            "title": "Pedestrian Hazard",
                            "text": "It is likely that members of the public will congregate in and/or around this area. Please be mindful of their safety."
                        },
                        {
                            "iconUrl": "https://www.altitudeangel.com/Map/Icon?icon=amenity_university.png",
                            "title": "Privacy Concerns",
                            "text": "This classification of area or point is likely to be additionally sensitive to privacy concerns. You may have greater obligations to disclose your intended flight over, within or near these areas to any controlling authority or land owner, particularly if you plan to fly with surveillance equipment."
                        }
                    ],
                    "actions": []
                }
            },
            "type": "Feature"
        },
        {
            "geometry": {
                "coordinates": [
                    [-0.1132399,51.5032168],[-0.1140898,51.5025247],[-0.1143532,51.5022606],[-0.1145354,51.5020728]
                ],
                "type": "LineString"
            },
            "id": "B84BAC3E146546690C53DC687692029CBD3D083D",
            "properties": {
                "fillColor": "#ffbb00",
                "fillOpacity": "0.35",
                "strokeColor": "#b88702",
                "strokeWidth": "1",
                "strokeOpacity": "0.8",
                "detailedCategory": "railway:rail",
                "iconUrl": "https://www.altitudeangel.com/Map/Icon?icon=railway_rail.png",
                "name": "railway rail",
                "category": "groundHazard",
                "filters": [
                    {
                        "name": "Ground Hazards",
                        "property": "show",
                        "active": true
                    }
                ],
                "display": {
                    "category": "Ground Hazard",
                    "detailedCategory": "railway rail",
                    "title": "Ground Hazard",
                    "sections": [
                        {
                            "iconUrl": "https://www.altitudeangel.com/Map/Icon?icon=railway_rail.png",
                            "title": "Rail Infrastructure",
                            "text": "Be aware that rail infrastructure is dangerous: fast-moving rolling-stock, electrified tracks, cables and/or signalling equipment exists that may not be individually mapped."
                        }
                    ],
                    "actions": []
                }
            },
            "type": "Feature"
        },
        {
            "geometry": {
                "coordinates": [
                    [
                        [-0.72798748237513211, 51.4170323569639], [-0.72776448814717509, 51.414586593414249], [-0.72715933621707063, 51.412166261383554], [-0.7261779100284258, 51.409794651887978]
                    ]
                ],
                "type": "Polygon"
            },
            "id": "8394F99ED2EC386749B3FDAFE67A29C55D1177EB",
            "properties": {
                "fillColor": "#FF0055",
                "fillOpacity": "0.35",
                "strokeColor": "#BF0442",
                "strokeWidth": "1",
                "strokeOpacity": "0.8",
                "detailedCategory": "class:tfr",
                "iconUrl": "https://www.altitudeangel.com/Map/Icon?icon=class_tfr.png",
                "name": "RESTRICTED AREA (TEMPORARY) AT ASCOT, BERKSHIRE FOR THE RED BULL AIR RACE 2016",
                "category": "airspace",
                "operationalTo": "2016-08-14T17:30:00Z",
                "filters": [
                    {
                        "name": "Temporary Flight Restriction",
                        "property": "show",
                        "active": true
                    },
                    {
                        "name": "Airspace",
                        "property": "show",
                        "active": true
                    },
                    {
                        "name": "Class  TFR",
                        "property": "show",
                        "active": true
                    }
                ],
                "display": {
                    "category": "airspace",
                    "airspaceClass": "G",
                    "designator": "EGLF",
                    "detailedCategory": "Class  TFR",
                    "title": "RESTRICTED AREA (TEMPORARY) AT ASCOT, BERKSHIRE FOR THE RED BULL AIR RACE 2016",
                    "sections": [
                        {
                            "iconUrl": "https://www.altitudeangel.com/Map/Icon?icon=warning.png",
                            "title": "Temporary Flight Restriction",
                            "text": "This is an official 'No Fly Zone' (a Temporary Flight Restriction) and it applies according to the following criteria, in the region indicated by the boundary shown."
                        },
                        {
                            "iconUrl": "https://www.altitudeangel.com/Map/Icon?icon=warning.png",
                            "title": "Activation Details",
                            "text": "Status: 08:00 hours on 11 August until 17:30 on 14 August 2016 (UTC)"
                        },
                        {
                            "iconUrl": "https://www.altitudeangel.com/Map/Icon?icon=warning.png",
                            "title": "Controlled Airspace",
                            "text": "This airspace has a specific classification which applies to manned aviation, and may have implications on drone operations depending on local laws and regulations governing drone use.\r\n\r\nRegulations governing the flight of drones vary from country-to-country, therefore these areas are included for your information. It is your responsibility to check the applicability of any local, state and/or national laws and regulations which may permit or otherwise restrict the operation of your drone. Unless regulations in your region explicitly permit the operation of your drone in this area, we recommend you do not operate your drone here."
                        }
                    ],
                    "actions": [
                        {
                            "description": "Further Details",
                            "uri": "http://www.nats-uk.ead-it.com/fwf-natsuk/restricted/user/ino/brief_overview.faces",
                            "iconUrl": null
                        }
                    ]
                }
            },
            "type": "Feature"
        },
        {
            "geometry": {
                "coordinates": [
                    [
                        [ -0.73049178301143347, 51.304656930751918], [-0.73284759492371676, 51.306068256309516], [-0.73531119438880033, 51.307405375802524], [-0.7378766433612769, 51.308665061416555]
                    ]
                ],
                "type": "Polygon"
            },
            "id": "F47836AB8A524FA0D3B25BCCC78D9A564258540E",
            "properties": {
                "fillColor": "#FF0055",
                "fillOpacity": "0.35",
                "strokeColor": "#BF0442",
                "strokeWidth": "1",
                "strokeOpacity": "0.8",
                "detailedCategory": "type:atz",
                "iconUrl": "https://www.altitudeangel.com/Map/Icon?icon=class_type_atz.png",
                "name": "FARNBOROUGH",
                "category": "airspace",
                "airac": {
                    "to": "2016-08-18",
                    "from": "2016-07-21"
                },
                "filters": [
                    {
                        "name": "Airspace",
                        "property": "show",
                        "active": true
                    },
                    {
                        "name": "Type ATZ",
                        "property": "show",
                        "active": true
                    }
                ],
                "display": {
                    "category": "airspace",
                    "detailedCategory": "Type ATZ",
                    "title": "FARNBOROUGH",
                    "sections": [
                        {
                            "iconUrl": "https://www.altitudeangel.com/Map/Icon?icon=warning.png",
                            "title": "Controlled Airspace",
                            "text": "This airspace has a specific classification which applies to manned aviation, and may have implications on drone operations depending on local laws and regulations governing drone use.\r\n\r\nRegulations governing the flight of drones vary from country-to-country, therefore these areas are included for your information. It is your responsibility to check the applicability of any local, state and/or national laws and regulations which may permit or otherwise restrict the operation of your drone. Unless regulations in your region explicitly permit the operation of your drone in this area, we recommend you do not operate your drone here."
                        }
                    ],
                    "actions": []
                }
            },
            "type": "Feature"
        }
    ],
    "bbox": [
        -0.115996261299187,
        51.498511099924983,
        -0.10148014611058898,
        51.50490920528491
    ],
    "type": "FeatureCollection"
}

Sample Limit-breached Response

{
    "isCompleteData": false,
    "excludedData": [
        {
            "message": "Request must include a bounding rectangle under 20,000,000 square meters.",
            "detail": {
                "name": "Ground Hazards"
            },
            "errorReason": "QueryAreaTooLarge"
        }
    ],
    "features": [

    ],
    "bbox": [
        -1.0776117916595922,
        51.24434951896064,
        -0.1396540279877172,
        51.652165139566279
    ],
    "type": "FeatureCollection"
}

Updated 23 days ago

Map Data


This endpoint returns data in GeoJSON format (see https://tools.ietf.org/html/rfc7946) which is supported by most common mobile and web map controls, and is ideal for anyone wanting to work directly with the data available on our maps. However, if you just want an embeddable version of our map, take a look at our Embeddable Map.

Suggested Edits are limited on API Reference Pages

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