DocsHelp
Docs
Your API KeySupportaltitudeangel.com

Tower

The Tower API has responsibility for providing information similar to that which an airport tower would return to a pilot. Principally, this is localised information about a specific area's environmental conditions, or to obtain a summary of the known risks and hazards present at a given geography.

Tower is designed to be called at least once per flight. Many developers call it once during the pre-flight planning phases, often days in advance of the actual flight, and then submit a final check again just prior to take-off.

Suggest Edits

This API allows you to query the "tower" for a situational awareness report. Each report can be comprised of one or more types, as defined below:

TypeDescription
weatherGiven a coordinate, provides the latest observed and 1 hour forecast weather.
advisoriesGiven a polygon, provides a detailed report of the hazards in the region and provides an overall status indicator.

Tower has been designed to deliver information about the immediate area of operation directly to a drone, or for use within a control station/flight planning app.

Obtaining reports

📘

Security

All requests require OAUTH or API-key authentication and access to the talk_tower scope.

Obtaining a situation report

Functionally, the /report endpoint provides a situation awareness report per request. Each report is scoped to a specific coordinate, or a defined geometry, and may comprise one or more type. In this way, it is possible to request a comprehensive report comprising many factors, or scope your request for a tightly-focused report.

Semantically, you'll note that the position you specify is a child of the flight object. Reports are designed to be obtained at least once immediately prior to taking-off. However, many people make multiple calls well in advance of the flight, typically during the flight planning/risk assessment stage.

https://api.altitudeangel.com/ops/tower/report

Sample request

Let's take a look at a sample request specifying a pos (coordinate) and requesting weather. A full explanation of each parameter is below the sample:

POST https://api.altitudeangel.com/ops/tower/report
Authorization: X-AA-ApiKey YOUR_API_KEY

{
    "flight": {
        "pos": {
            "lat": 55.4298566270507,
            "lng": -4.504291076432537
        }
    },
    "aircraft": {
        "id": "empty",
        "takeoffWeightKg": null
    },
    "types": [
        "weather", "..."
    ]
}

🚧

Specifying geography

The flight object will accept either a pos, geometry (eg. polygon) or bounds to describe the location in which you would like the report to cover. In the event you specify a pos, we will automatically append a circle with radius 500 metres centred on the point you have specified, and base the report output on this area.

An example specifying a geometry instead of a pos:

"geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              -1.1370849609375,
              51.605651030611924
            ],
            [
              -1.12884521484375,
              51.64614620689681
            ],
            [
              -1.0594940185546875,
              51.64657227968615
            ],
            [
              -1.0155487060546875,
              51.613752957501
            ],
            [
              -1.006622314453125,
              51.576642811561584
            ],
            [
              -1.07666015625,
              51.55444755572847
            ],
            [
              -1.1370849609375,
              51.605651030611924
            ]
          ]
        ]
}

Or, specifying a bounds (top and bottom corners of a box):

"bounds": {
    "sw":{
        "lat":0,
        "lng":0
    },
    "ne":{
        "lat":0,
        "lng":0
    }
}
PropertyDescription
flight.pos.latThe latitude of the flight takeoff
flight.pos.lngThe longitude of the flight takeoff
aircraft.idThe id of the aircraft for this flight. Must be "empty"
aircraft.takeoffWeightKgThe takeoff weight of the aircraft in kg. Must be null
typesArray of data to request in the report. Must be one or more of weather, advisories, with other values reserved for future use.

Note: the aircraft object is currently reserved for future use but we advise you to send the correct values to this endpoint if you have them.

Response format

Responses are returned as a JSON object with properties for each requested report type.

Sample weather

{
    "weather": {
        "forecast": {
            "current": {
                "summary": "Partly Cloudy",
                "temperatureC": 9.29,
                "at": "2017-01-16T15:15:23Z",
                "cloudCoverPercent": 55,
                "uvIndex": 0,
                "windDirection": "SSW",
                "windHeadingDegrees": 208,
                "windSpeedKph": 1.98,
                "precipitationPercent": 0,
                "humidityPercent": 93,
                "meanSeaLevelPressureHPa": 1028,
                "dewPointC": 8.27,
                "snowMillimeters": 0,
                "rainfallMillimeters": 0
            },
            "upcoming": {
                "summary": "Mostly Cloudy",
                "temperatureC": 9.38,
                "at": "2017-01-16T17:00:00Z",
                "cloudCoverPercent": 87,
                "uvIndex": 0,
                "windDirection": "SSW",
                "windHeadingDegrees": 203,
                "windSpeedKph": 1.5,
                "precipitationPercent": 1,
                "humidityPercent": 96,
                "meanSeaLevelPressureHPa": 1028,
                "dewPointC": 8.78,
                "snowMillimeters": 0,
                "rainfallMillimeters": 0
            },
            "effective": {
                "start": "2017-01-16T15:15:23Z",
                "end": "2017-01-16T18:00:00Z",
                "approx": false,
                "type": "timeRange"
            },
            "geography": {
                "center": {
                    "lat": 55.4298566270507,
                    "lng": -4.504291076432537
                },
                "radius": 10000.0,
                "numPoints": 100,
                "type": "circle"
            }
        }
    }
}

Sample advisories

📘

Advisories

Advisories are useful for summarising the severity and nature of the hazards within a given geography. In the example below, we return an overall summary indicating a hazardFactor of 60, which is translated into an English string hazardFactorName of Danger.

To build conditional logic within your apps that are dependent on the output of this call, we do not recommend you bind to the string fields, instead using the integers as we may change the definitions/string values that correspond to the integer values at any time.

🚧

Hazard Factors

Higher values for hazardFactor indicated higher severity items.

The response consists of a summary with an overall hazard factor along with a breakdown by feature category, along with an array of the map features that were included in the analysis.

These features can be cross referenced against the map data via their id which is consistent with the map data downloaded from the Map Data endpoint.

{
  "advisories": {
    "summary": {
      "overall": {
        "hazardFactorName": "Danger",
        "hazardFactor": 60
      },
      "categories": {
        "groundHazard": {
          "hazardFactorName": "Warning",
          "hazardFactor": 40
        },
        "risk": {
          "hazardFactorName": "Warning",
          "hazardFactor": 40
        },
        "airspace": {
          "hazardFactorName": "Danger",
          "hazardFactor": 60
        },
        "flightReport": {
          "hazardFactorName": "Information",
          "hazardFactor": 20
        }
      }
    },
    "features": [
      {
        "id": "73A18AC20DABDAEC46108A65D5C2BBE696FDF4F7",
        "name": "RAF Benson",
        "category": "groundHazard",
        "detailedCategory": "aeroway:aerodrome",
        "hazardFactorName": "Warning",
        "hazardFactor": 40
      },      
      {
        "id": "935A7411ADBEBA1CFD266B68E01FA40BC824942A",
        "name": "Crowmarsh Gifford Primary School",
        "category": "groundHazard",
        "detailedCategory": "amenity:school",
        "hazardFactorName": "Warning",
        "hazardFactor": 40
      },
      // Other results truncated for sample clarity ... 
      {
        "id": "02d98bba-794d-4be6-bc0d-1a0f1f9c772e",
        "name": "Chimney inspection",
        "category": "flightReport",
        "detailedCategory": "user:flight_report",
        "hazardFactorName": "Information",
        "hazardFactor": 20
      }
    ]
  }
}

Updated about 3 years ago