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.
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:
Type | Description |
---|---|
weather | Given a coordinate, provides the latest observed and 1 hour forecast weather. |
advisories | Given 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.
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 apos
,geometry
(eg. polygon) orbounds
to describe the location in which you would like the report to cover. In the event you specify apos
, 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
}
}
Property | Description |
---|---|
flight.pos.lat | The latitude of the flight takeoff |
flight.pos.lng | The longitude of the flight takeoff |
aircraft.id | The id of the aircraft for this flight. Must be "empty" |
aircraft.takeoffWeightKg | The takeoff weight of the aircraft in kg. Must be null |
types | Array 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 ahazardFactor
of 60, which is translated into an English stringhazardFactorName
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 almost 3 years ago