Contents
Introduction
Aircraft definitions contain data about the aircraft type, callsign, ATC and search & rescue equipment as well as performance data, allowing the autorouter to understand its flight profile characteristics and choose the optimum routes.
Autorouter allows a user to persistently store aircraft definitions and refer to them by a unique aircraft ID. Aircraft are private to a user and not shared.
For usage scenarios, where a persistent storage of aircraft definitions is not desired, it is also possible to work with complete aircraft definitions in lieu of an aircraft ID. Other APIs that require an aircraft definition will either accept the ID or the complete definition as outlined in this section.
Aircraft Definition
Aircraft are defined in JSON structures as explained in the following example.
{
// ICAO callsign, required field
"callsign": "DEABC",
// year of construction, required for persistent aircraft definitions
"year": 1976,
// ICAO type name, required field
"icaotypename": "C172",
// name of the manufacturer, optional
"manufacturername": "Cessna",
// model name, required for persistent aircraft definitions
"modelname": "172",
// comment to be prepended to RMK/ in item 18, optional
"rmk": null,
// comment string for human use, optional
"comment": "",
// homebase ICAO code, optional
"homebase": "EDDS",
// EU VAT status free circulation, optional
"freecirculation": true,
// ICAO equipment codes, required
"equipment": "SBDGRY",
// ICAO transponder codes, required
"transponder": "S",
// optional CODE/ field for other info in flight plan
"code": "",
// optional COM/ field for other info in flight plan
"com": "",
// optional NAV/ field for other info in flight plan
"nav": "",
// optional DAT/ field for other info in flight plan
"dat": "",
// optional STS/ field for other info in flight plan
"sts": "",
// optional SUR/ field for other info in flight plan
"sur": "",
// optional PER/ field for other info in flight plan
"per": "",
// optional OPR/ field for other info in flight plan
"opr": "",
// ICAO PBN group, required when "R" is present in equipment code
"pbn": "B2D2S1",
// standard endurance in minutes
"endurance": 220,
// extra fuel for taxi in fuel units, default 0
"taxifuel": 0,
// fuel flow for taxi in fuel units per hour, default 0
"taxifuelflow": 0,
// contingency fuel in percent of route fuel, default 5
"contingencyfuel": 5,
// name of pilot in command, default empty
"picname": "GRIM REAPER",
// crew contact information, default empty
"crewcontact": "+49170123456789",
// aircraft color markings, default empty
"colormarking": "white with blue",
// ICAO radio emergency codes, default none
"emergencyradio": "",
// ICAO survival equipment codes, default none
// use "-" for standard equipment without features
"survival": "",
// ICAO life jackets equipment codes, default none
// use "-" for standard jackets without features
"lifejackets": "",
// number of dinghies on board, default 0
"dinghies": 0,
// capacity of dinghies in number of persons
"dinghycapacity": 0,
// flag whether dinghies have covers, default false
"dinghycover": false,
// dinghy color, default empty
"dinghycolor": "",
// climb speed in KCAS knots, required when climb table mode is "rateofclimb"
"vy": 70,
// descent speed in KCAS knots, required when descent performance
// data is expressed as rates of descent
"vdescent": 120,
// maximum break horse power
"maxbhp": 150,
// aircraft propulsion type, can be one of
// - fixedpitch
// - constantspeed
// - turboprop
// - turbojet
"propulsion": "fixedpitch",
// fuel mass in massunit
"fuelmass": 6,
// ICAO noise level, optional and can be empty
"noise": [
{
// ICAO noise certification chapter according to ICAO Annex 16 Volume 1
"chapter": 10,
// noise level in dB(A)
"value": 77.4
}
],
// climb performance table, required, array of climb "curves"
"climb":
[
{
// unique user readable name of the climb settings curve
"name": "Standard",
// ceiling in feet for that curve. If another curve gives a higher
// ceiling, the router switches to it when the chosen curve is exhausted
"ceiling": 20000,
// the aircraft mass in aircraft mass units for which this curve is valid
// the closest one is chosen by the router
"mass": 1043,
// ISA temperature offset of this curse. The router performs interpolation
"isaoffs": 0,
// there are two ways of specifying climb data: "rateofclimb"
// and "timetoaltitude". The former gives a list of climb rates,
// the latter a table with time, fuel and distance to altitude
"mode": "rateofclimb",
// the climb data for different altitudes
"points":
[
{
// pressure altitude in feet above MSL
"pa": 0,
// climb rate in feet per minute
// only given when mode is "rateofclimb"
"rate": 400,
// fuel flow in fuel units per hour
// only given in "rateofclimb" mode
"ff": 13.2086
// time in seconds, only given in "timetoaltitude" mode
// "time": 60
// fuel in aircraft fuel units, only in "timetoaltitude" mode
// "fuel": 15
// distance travelled in NM, only in "timetoaltitude" mode
// "distance": 3.5
},
// at least two climb performance data points should be given, one
// at MSL, the other at the service ceiling. Linear interpolation is
// used between the data points.
{
"pa": 12000,
"rate": 50,
"ff": 10.56688
}
]
}
],
// cruise performance data, array of cruising curves ("settings")
"cruise":
[
{
// configurable name to identify the setting
"name": "Normal",
// aircraft mass in aircraft mass units, defaults to MTOM
"mass": 1043,
// ISA temperature offset in degrees Celcius, defaults to 0
// the tuple (name, mass, isaoffs) needs to be unique
"isaoffs": 0
// this can either be "interpolate" or "hold". The former are normal
// cruise settings where the system will interpolate from the data given
// and the latter is a special holding setting which can only appear once
// and is used to calculate the required fuel in the holding
"flags": "interpolate",
// list of cruise performance data points
"points":
[
{
// pressure altitude in feet above MSL
"pa": 0,
// fuel flow in fuel units per hour
"ff": 10.56688,
// break horse power
"bhp": 98,
// true airspeed in knots
"tas": 105
},
{
"pa": 5000,
"ff": 10.56688,
"bhp": 98,
"tas": 105
},
// at least 3 cruise performance points should be given, best is to have
// - one at or near MSL
// - one at mid point
// - one near the service ceiling
// Note that especially normally aspirated piston aircraft tend to have
// a "sweet spot" at around 8000ft which should be given.
{
"pa": 7500,
"ff": 10.56688,
"bhp": 98,
"tas": 110
},
{
"pa": 12000,
"ff": 10.56688,
"bhp": 98,
"tas": 110
}
]
}
],
// descent performance data, can take two shapes: either a fixed descent rate
// in feet per minute (fpm) or descent curves similar to climb
/* "descent":
{
// the default is 1000fpm
"rate": 1000
}, */
/* descent table in case the above fixed rate is not present */
"descent":
[
{
// the mode of the curve, all curves need to have the same mode
"mode": "timefromaltitude",
// configurable name to identify
"name": "Normal",
// ceiling in feet from which this curve is valid
"ceiling": 20000,
// aircraft mass in aircraft mass units, defaults to MTOM
"mass": 1043,
// ISA temperature offset in degrees Celcius, defaults to 0
// the tuple (name, mass, isaoffs) needs to be unique
"isaoffs": 0,
"points":
[
{
// pressure altitude in feet from which to start descent
"pa": 20000,
// time in seconds from the pressure altitude to MSL
"time": 600,
// distance covered in NM from PA to MSL
"distance": 50,
// fuel consumed in aircraft fuel units from PA to MSL
"fuel": 60
}
]
}
/*
{
// rate of descent mode
"mode": "rateofdescent",
"points":
[
{
// pressure altitude in feet for which descent data is valid
"pa": 20000,
// fuel consumption in aircraft fuel units per hour
"ff": 50,
// descent rate in feet per minute (fpm)
"rate": 1000
}
]
}
*/
],
// optional drift down curves to model glide performance
glide: [
{
// the mode of the curve, all curves need to have the same mode
"mode": "timefromaltitude",
// aircraft mass in aircraft mass units, defaults to MTOM
"mass": 1043,
// ISA temperature offset in degrees Celcius, defaults to 0
// the tuple (name, mass, isaoffs) needs to be unique
"isaoffs": 0,
"points": [
{
// pressure altitude in feet from which to start glide
"pa": 20000,
// time in seconds from the pressure altitude to MSL
"time": 500,
// distance covered in NM from PA to MSL
"distance": 30
}
]
}
/*
{
// rate of descent mode
"mode": "rateofdescent",
"points": [
{
// pressure altitude in feet for which descent data is valid
"pa": 20000,
// descent rate in feet per minute (fpm)
"rate": 1200,
// calibrated airspeed in aircraft speed units
// this corresponds to Vbg at the given altitude, mass, atmosphere
"cas": 134
}
],
// if the glide ratio and Vbg is the same throughout the altitude range,
// pass an empty points array and specify the following two attributes
// fixed Vbg in aircraft speed units
"vbestglide": 134
// fixed glideslope as a factor of altitude loss
"glideslope": 10.3
}
*/
],
// weight & balance section, required
"wb":
{
// maximum takeoff mass in massunit, required
"mtom": 1043,
// maximum landing mass in massunit
"mlm": 1043,
// maximum ramp mass in massunit
"mrm": 1050,
// mass arm unit name (in, cm), default "in"
"armunitname": "in",
// mass unit name (kg, lb), default "lb"
"massunitname": "lb",
// the loading stations, optional
"stations":
[
// this station is required for the basic empty mass
{
"name": "Basic Empty Mass",
// flags can be:
// - "fixed" (non configurable item)
// - "avgas" (AVGAS fuel tank)
// - "jeta" (Jet A-1 fuel tank)
// - "seating" (passenger/crew) seats, additional "seats" attribute
// with number of seats required
// - "" (standard loading element)
"flags": "fixed",
// maximum permitted mass in station in mass unit
"massmax": 700
// arm in arm unit
"arm": 95
},
{
"name": "Front Row",
"flags": "seating",
"seats": 2,
"massmax": 200,
"arm": 94
},
// this illustrates a variable arm fuel station
{
"name": "Extra fuel",
"flags": "jeta",
"massmax": 200,
// arm is an array instead of a number. Interpolation
// is performed between the data points
"arm":
[
{
"mass": 100,
"arm": 104
},
{
"mass": 200,
"arm": 107
}
]
},
{
"name": "Back row",
"flags": "seating",
"seats": 3,
"massmax": 200,
"arm": 188
},
{
"name": "Baggage",
"flags": "",
"massmax": 40,
"arm": 246
}
],
// the loading envelope, optional and replacing the legacy "envelope"
// this one should be used instead of the legacy. The legacy member will be
// ignored on input in case this one is present. On output, the legacy member is
// always populated for compatibility reasons, see below
"envelopes": [
{
// the name of the envelope, the standard/first/only one is usually called "Normal"
"name": "Normal",
// the edges of the permitted loading diagram starting with the lowest mass
// and lowest forward COG arm and then going counter-clockwise
"points": [
{
// mass in mass units of the edge
"mass": 700,
// arm in arm units
"arm": 84
},
{
"mass": 700,
"arm": 119
},
{
"mass": 1043,
"arm": 119
},
{
"mass": 1043,
"arm": 104
},
{
"mass": 850,
"arm": 91
}
]
}
],
// the loading envelope, optional
// this is a legacy interface and only used when the newer "envelopes" member
// supporting multiple loading envelopes is not present. You should not use this
// member neither when receiving nor when submitting aircraft definitions. For
// compatibility, it is always returned and contains the envelope with the name
// "Normal" or the first one in case none with that name exists.
"envelope":
[
// the edges of the permitted loading diagram starting with the lowest mass
// and lowest forward COG arm and then going counter-clockwise
{
// mass in mass units of the edge
"mass": 700,
// arm in arm units
"arm": 84
},
{
"mass": 700,
"arm": 119
},
{
"mass": 1043,
"arm": 119
},
{
"mass": 1043,
"arm": 104
},
{
"mass": 850,
"arm": 91
}
]
},
// takeoff and landing distances, optional
"distances":
{
// unit for the distances (ft, m), default feet
"unitname": "ft",
// rotation speed, default 70
"vrotate": 70,
// takeoff distance information, optional
// you should supply at least two datapoints for landing and takeoff
// to enable interpolation. All data is at MTOM.
"takeoff":
[
{
// density altitude in feet
"da": 0,
// ground roll distance in units
"gnddist": 250
// distance until passing of 50ft obstacle in units
"obstdist": 470
},
{
"da": 5000,
"gnddist: 500,
"obstdist": 750
}
],
// landing distance information, optional
// all data is at MTOM
"landing":
[
{
// density altitude in feet
"da": 0,
// ground roll distance in units
"gnddist": 183,
// distance from passing of 50ft obstacle in units
"obstdist": 402
},
{
"da": 8000,
"gnddist": 240,
"obstdist": 483
}
]
},
// manufacturer code from autorouter, required for persistent definition
"manufacturer": 888,
// ICAO type code from autorouter, required for persistent definition
"icaotype": 390,
// standard maximum flight level, required for persistent definition
"defaultmaxfl": 60,
// speed unit, can be kts, kph or mph, required for persistent definition
// note that all speeds in the aircraft definition are always given in knots
// this field only benefits user interfaces that can convert knots to the unit
// chosen by the user
"speedunit": "kts",
// fuel unit, can be l, usgal, lb or kg, required for persistent definition
"fuelunit": "l"
}
Create aircraft
To create a persistent aircraft definition, issue the following call with the aircraft definition in the body of the request.
HTTP POST to https://api.autorouter.aero/v1.0/aircraft
If successful, status code 200 and the ID of the newly created aircraft is returned.
Retrieve aircraft definition
To retrieve the JSON representation of an aircraft, issue the following request.
HTTP GET to https://api.autorouter.aero/v1.0/aircraft/<id>
To retrieve the publicly accessible definition of an aircraft template, refer to the template by its aircraft id and pass the public parameter:
HTTP GET to https://api.autorouter.aero/v1.0/aircraft/<template id>?public
Modify aircraft
To modify the definition of an existing aircraft, you have to first retrieve it, perform the modification and then submit the modified structure with the following request.
HTTP PUT to https://api.autorouter.aero/v1.0/aircraft/<id>
Note that the aircraft definition will be completely replaced after issuing this command.
Remove aircraft
To delete an aircraft definition, issue the following command.
HTTP DELETE to https://api.autorouter.aero/v1.0/aircraft/<id>
Make aircraft the default aircraft
The following request sets the default flag on the given aircraft. This is the aircraft that is selected by default when creating a new route (only relevant for the user interface).
HTTP PUT to https://api.autorouter.aero/v1.0/aircraft/<id>/default
Get list of manufacturers
For persistent aircraft definitions, a manufacturer referenced by its ID is required. The list of defined manufacturer can be retrieved as follows.
HTTP GET to https://api.autorouter.aero/v1.0/aircraft/manufacturer
The response is a JSON array with the following structure.
[
{
"id": 5,
"name": "Cessna Aircraft Corporation"
}
]
Get list of aircraft types
For each manufacturer, you can retrieve a list of available aircraft types as follows.
HTTP GET to https://api.autorouter.aero/v1.0/aircraft/manufacturer/<manufacturerid>/types
The returned JSON data is structured in the following way.
[
{
// ICAO aircraft type
"icao": "A306",
// ID of aircraft type, referenced in aircraft structure
"id": 17,
// manufacturer ID
"manufacturer": 887,
// aircraft type description
"type": "A300B4-600 /C4-600 / F4-600",
// ICAO wake category letter (L/M/H/S)
"wakecategory": "H"
}
]
Get aircraft templates
The system maintains a list of aircraft templates which can be used when creating a new aircraft. The list of templates is obtained by the following request.
HTTP GET to https://api.autorouter.aero/v1.0/aircraft/templates
The returned JSON structure looks as follows.
[
{
"id": 391,
"manufacturer": "Beech",
"manufacturerid": 942,
"model": "Bonanza A36 (1984)"
}
]
The aircraft details are then retrieved by requesting the aircraft ID passed in the template entry and specifying the public option on the GET request.
In order to only display templates for a given ICAO aircraft ID (e.g. “C182”), use the following invocation:
HTTP GET to https://api.autorouter.aero/v1.0/aircraft/templates/<icao>
List aircraft of user
The following call retrieves a list of all aircraft that are defined for the current user.
HTTP GET to https://api.autorouter.aero/v1.0/aircraft?page=1&rows=10
The returned JSON data looks as follows:
{
// which page was returned
"page": 1,
// number of total records
"records": 1,
"rows":
[
{
"callsign": "DEXXX",
// whether it's the user's default aircraft
"default": true,
"id": 123,
"manufacturer": "Cessna",
"model": "TR182",
"year": 1979
}
]
// number of total pages
"total": 1
As you can see, this request implements pagination to deal with the potentially large number of aircraft. The request supports a few parameters:
- rows
Number of rows that can be returned on one page. - page
The number of the result page request, 1 is the first. - sidx
Name of the field to sort, can be “callsign” or “description”. - sord
Search order, can be “asc” or “desc”. - _search
Whether a search for field content is performed, “true” for yes. - searchField
The name of the field that should be searched in, can be “callsign” or “description”. - searchString
The text to search for.
Calculate performance model
To help developers understand how aircraft settings impact the performance model, there is an API call returning aircraft performance data derived from the data configured. The “Visualize” button on the aircraft settings page provides a graphical interface to the API.
HTTP POST to https://api.autorouter.aero/v1.0/aircraft/performance?isaoffs=0[&mass=1500][&powersetting=Max]
All parameters are optional and defined as follows:
- isaoffs
The ISA (international standard atmosphere) temperature offset in degrees Kelvin. The default of 0 means 15°C at MSL and 2°K temperature drop per 1000ft. - mass
The aircraft mass in aircraft mass units, default is MTOM. - powersetting
The name of the cruise power setting. If not specified, the default powersetting is used.
The returned JSON structure contains some basic aircraft information as well as the calculated ceiling in feet (it can be different from the specified ceiling if the supplied data does not allow the aircraft to reach the configured ceiling) and an array of performance numbers from MSL up to the ceiling in 100ft increments. An entry could look as follows:
{
/* break horse power, only applicable for pistons */
"bhp": 153.75,
/* calibrated airspeed (kt) in cruise */
"cas": 130.16436767578,
/* calibrated airspeed for climb */
"climbcas": 91.634658813477,
/* distance covered in climb since first entry (MSL) */
"climbdist": 2.0849206593884,
/* fuel consumed in climb in aircraft fuel units */
"climbfuel": 2.156144159784,
/* fuel flow during climb */
"climbfuelflow": 99.000000001806,
/* name of climb profile used (currently hardcoded to "Normal") */
"climbname": "Normal",
/* climb rate in feet per minute */
"climbrate": 806.22952899428,
/* true airspeed in climb */
"climbtas": 96.478501849729,
/* time in seconds since start of climb in first entry */
"climbtime": 78.405242172533,
/* density altitude in feet */
"densityalt": 1066.8006591797,
/* calibrated airspeed in knots for descent */
"descentcas": 125.92399597168,
/* distance in NM until end of descent at MSL */
"descentdist": 2.3394407595519,
/* fuel required in aircraft fuel units until the end of descent at MSL */
"descentfuel": 0.76943356259833,
/* fuel flow in aircraft fuel units for descent */
"descentfuelflow": 43.4467959475,
/* name of powersetting used for descent */
"descentname": "2100 RPM",
/* current rate of descent in feet per minute */
"descentrate": 999.99353967492,
/* true airspeed in knots for descent */
"descenttas": 132.54218789809,
/* time in seconds until end of descent at MSL */
"descenttime": 64.010849768695,
/* equivalent airspeed in knots for cruise */
"eas": 130.07962036133,
/* fuel flow in aircraft fuel units for cruise */
"fuelflow": 44,
/* whether the entry is for a holding */
"hold": false,
/* whether interpolation was performed */
"interpolate": true,
/* ISA offset in degrees Kelvin */
"isaoffs": 0,
/* flight level of entry */
"level": 35,
/* local speed of sound in knots */
"lss": 653.43475341797,
/* cruise mach speed */
"mach": 0.20966136455536,
/* aircraft mass in aircraft mass units */
"mass": 1406,
/* name of cruise power setting */
"name": "2100 RPM",
/* outside air temperature in degrees Celcius */
"oat": 8.0657958984375,
/* pressure altitude in feet */
"pressurealt": 3500,
/* QNH in millibars */
"qnh": 1013.25,
/* ram air temperature in degrees Celcius */
"rat": 10.550506591797,
/* true airspeed in knots */
"tas": 137,
/* true altitude in feet */
"truealt": 3500.0026855469
}