Contents
- 1 Introduction
- 2 Validate a flight plan
- 3 Parse/modify flight plan
- 4 List filed flight plans
- 5 Retrieve flight plan details
- 6 File flight plan
- 7 Delay flight plan
- 8 Cancel flight plan
- 9 Bring forward flight plan
- 10 Send departure message
- 11 Send arrival message
- 12 Flight plan status codes
- 13 FPAL related functions
Introduction
Flight plans can be referenced in several ways throughout the application:
- As a flight plan string in ICAO format;
- via the route ID, this would be the last produced flight plan for that route as stored in the database;
- as a flight plan ID corresponding to a plan that was filed;
- as a list of waypoints for ad-hoc flight plans
Several operations can be performed on flight plans.
Validate a flight plan
A flight plan in ICAO format can be validated using the following call.
HTTP GET https://api.autorouter.aero/v1.0/flightplan/validate?fpl=(FPL-.......)
The flight plan is added as a query parameter. The call returns JSON which contains the validation result as returned by IFPS.
{
"validation": "NO ERRORS"
}
or in case of an error, all errors are returned.
{
"validation": "PROF206: THE DCT SEGMENT BANUB .. POKEN IS NOT AVAILABLE IN FL RANGE F130..F130 (UNAVAILABLE ROUTE Z212)"
}
The errors are separated by newline.
Parse/modify flight plan
A flight plan can be parsed and its individual fields and associated data returned via one of two calls.
HTTP GET https://api.autorouter.aero/v1.0/flightplan/parse
HTTP GET https://api.autorouter.aero/v1.0/flightplan/<route id>
The first call passes the flight plan as a parameter to the HTTP request whereas the second variant references a route ID as part of the URL. For the first call, either the parameter “fpl” or the parameter “waypoints” must be set, containing a complete flightplan in ICAO format for the former and a list of waypoints for an ad hoc flightplan in the latter case. Optionally an aircraft ID can be passed with the “aircraft” parameter, for example
HTTP GET https://api.autorouter.aero/v1.0/flightplan?aircraftid=12&fpl=-(FPL-DEDGK-ZG%20-1C82R/L%20-SDFGRY/S%20-EDTH0943%20-N0138VFR%20RIXED/N0138F040%20IFR%20DCT%20ERNAS%20DCT%20MAMOR%20DCT%20-EDMS0046%20-PBN/A1B2S1%20EET/RIXED0010%20)
or
HTTP GET https://api.autorouter.aero/v1.0/flightplan/EDTH-EDMS-asd23jk2
Through a list of options, the returned data can be influenced:
- gfs
When set to “yes”, GFS wind forecasts are applied and the data is returned for both with the forecast and and without. When set to “no” (default), no wind forecast data is applied. - addresses
Can be “yes” or “no” (default) and specifies whether flight plan addressing calculations should be performed and returned. - fireet
When set to “addall”, the flight plan will have EET groups for every FIR crossing and flight rule change. When set to “clear”, these groups are removed when present in the passed flight plan, when set to “add” (the default value), the flight plan will have EET groups for every flight rule change and every FIR crossing that is not under IFR within the Eurocontrol zone. When set to “”, no change to FIR crossing groups is performed. - eetobj
When set to “yes” (default), it returns an object representation of the EET group. - joiningeet
Can be “add” (default) or “clear” and specifies whether EETs will be issued for IFR joining on Z plans. - gramet
When set to “yes”, a GRAMET weather chart for the given flight plan is returned as PDF. Note that the flight plan data is not returned when this flag is set. - plog
When set to “yes”, a navigation log for the given flight plan is returned as PDF. Note that the flight plan data is not returned when this flag is set. - terraincorridor
A corridor in nautical miles around the route for which terrain calculations are performed. Default is 0 which means no calculation. When greater than zero, each waypoint in the fplan array contains a member terrain which indicates the maximum elevation inside the corridor in feet as well as a member msa that is set to 1000 feet above terrain when below 5000 ft altitude, otherwise 2000 ft above terrain. The corridor is from the waypoint to the next with the width passed in this parameter. - linebreaks
Can be “yes” or “no” (default) and specifies whether there should be linebreaks in the flight plan after each item. - annotatestdroute
Can be “yes” or “no” (default) and specifies whether route portions that belong to a standard route segment should be marked as such. Requires additional computing time when enabled. - atccharges
Can be “yes” or “no” (default) and specifies whether the ATC route charges should be calculated and returned.
To modify individual items of the plan before returning it, the following options can be passed:
- depnotbefore
Earliest possible departure time in seconds since the Unix epoch. Defaults to 5 minutes from now. - depnotafter
Latest possible departure time in seconds since the Unix epoch. Defaults to the maximum integer value. - departuretime
Departure time in seconds since the Unix epoch. Will be clamped by “depnotbefore” and “depnotafter”. - item15
Replace the route information. - waypoints
Replace the route information with a list of waypoints. - alternate1
First alternate airport. Set to empty string to remove. - alt1fplan
ICAO flight plan for route to first alternate. - alt1routeid
Route ID for flight plan to first alternate. Takes precedence over alternate1 and alt1fplan. - alternate2
Second alternate airport. Set to empty string to remove. - alt2fplan
ICAO flight plan for route to second alternate. - alt2routeid
Route ID for flight plan to second alternate. Takes precedence over alternate2 and alt2fplan. - fuelonboard
Fuel on board in aircraft fuel units. The endurance is then adjusted based on the aircraft’s performance model. - endurance
Aircraft endurance in seconds. - personsonboard
Number of persons on board, can be a number or “TBN”. - picname
Name of the pilot in command. - emergencyradio
Emergency radio string. - survival
Survival equipment string. - lifejackets
Life jacket equipment string. - dinghies
Dinghy equipment string. - aircraftid
Set a flight ID. The aircraft’s callsign which is the default flight ID will be returned with the REG/ option. - operator
Aircraft operator name. - crewcontact
Crew contact information (phone number). - asl
Airport slot number. - rmk
Remark. - flighttype
Type of flight (G = GA, X = Training, etc.).
The result returned is very similar to the solution and fpl command when routing but contains some additional information and uses more precise mathematics at the expense of performance.
{
// flight plan target addresses and warnings/information, resolved using
// the current FPAL documents. Only returned when "addresses" is set to "yes"
"addresses": [
{
"addr": "EDDXYIYR",
"doctype": "icaofpl",
"extension": "txt",
"format": "text",
"gar": false,
// FPAL rule names triggering this address
"idents": ["ED_MIXED"],
"type": "aftn",
// FPAL rule UUIDs triggering this address
"uuids": ["6597dc8e-2330-4b33-8008-23b036b04f37"]
},
{
"addr": "DEST SLOT required",
"doctype": "warning",
"extension": "txt",
"format": "text",
"gar": false,
"idents": ["ED_IFR_DESTSLOT"],
"type": "briefingpack",
"uuids": ["13ac99f7-7de0-4191-842b-16a7d236a8ee"]
}],
// flight plan in ADEXP format
"adexp": "-TITLE IFPL↵-ADEP EDTS↵-ADES EDDS↵-ARCID DEXXX↵-ARCTYP C82T↵-CEQPT SYDFGR↵-EOBD 170920↵-EOBT 1855↵-FLTTYP G↵-WKTRC L↵-TTLEET 0034↵-RFL F060↵-SPEED N0141↵-FLTRUL Z↵-SEQPT 256↵-ROUTE N0141F060 KUNOD/N0141F060 IFR DCT REUTL REUTL5A↵-ALTRNT1 EDSB↵-EETFIR EDMM 0019↵-EETPT KUNOD 0020↵-BEGIN RTEPTS↵-PT -PTID EDTS -FL F022 -ETO 170920190500↵-PT -PTID KUNOD -FL F060 -ETO 170920192522↵-PT -PTID REUTL -FL F060 -ETO 170920192958↵-PT -PTID STG -FL F060 -ETO 170920193849↵-PT -PTID EDDS -FL F013 -ETO 170920193927↵-END RTEPTS↵-DCT KUNOD REUTL↵-STAR REUTL5A↵"
// the aircraft callsign
"aircraftid": "DEXXX",
// aircraft ICAO type name
"aircrafttype": "C82T",
// aircraft type class per ICAO (light, 1 engine, piston, land)
"aircrafttypeclass": "L1PAL",
// route charges, only returned when "atccharges=yes" is passed
"atccharges": {
"cost": 0,
"vatcost": 0
},
// boundary box of the flight plan
"bbox": {
// north east latitude
"nelatdeg": 48.779445653781,
// north east longitude
"nelondeg": 9.6186113264412,
// swouth west latitude
"swlatdeg": 48.065834054723,
// south west longitude
"swlondeg": 8.0805558990687
},
// aircraft color markings form item 19
"colourmarkings": "WHITE AND BLUE",
// the ICAO flight plan string with all waypoints expanded (i.e. all waypoints on the same airway included)
"fpl": "(FPL-DEXXX-ZG -C82T/L -SYDFGR/S -EDTS1855 -N0141F060 KUNOD/N0141F060 IFR DCT REUTL REUTL5A -EDDS0035 EDSB -DOF/170919 EET/EDMM0019 KUNOD0020 RMK/TOW:1131 TAXI:10 PBN/A1B2S1 -E/0800 P/TBN R/E D/01 004 C RED A/WHITE AND BLUE)",
// the ICAO flight plan string as expected by ATC, this is usually the best variant to use as it does not contain unnecessary information (such as multiple points on the same airway) but also does not omit any information
"fplatc": "(FPL-DEXXX-ZG -C82T/L -SYDFGR/S -EDTS1855 -N0141F060 KUNOD/N0141F060 IFR DCT REUTL REUTL5A -EDDS0035 EDSB -DOF/170919 EET/EDMM0019 KUNOD0020 RMK/TOW:1131 TAXI:10 PBN/A1B2S1 -E/0800 P/TBN R/E D/01 004 C RED A/WHITE AND BLUE)"
// the flight plan waypoint array, first entry is the departure aerodrome,
// last entry the destination aerodrome. Alternates are not included.
"fplan": [
// same as in route request, not repeated here
],
// fuel calculation
"fuelcalc": {
// altitude in feet for trip to alternate
// only returned when alternate is configured
"altnalt": 5868,
// fuel required for trip to alternate in aircraft fuel units
// only returned when alternate is configured
"altnfuel": 15.21484,
// contingency fuel in aircraft fuel units
"contfuel": 1.55488,
// contingency fuel in percent of trip fuel, present if value is given
// in the aircraft definition
"contfuelpercent": 5,
// holding altitude in feet
"holdalt": 4000,
// holding fuel in aircraft fuel units
"holdfuel": 9,
// holding fuel flow in aircraft fuel units per hour
"holdfuelflow": 12,
// holding time in seconds
"holdtime": 2700,
// legal minimum fuel in aircraft fuel units
"reqdfuel": 56.86738,
// taxi fuel in aircraft fuel units
"taxifuel": 0,
// taxi fuel flow in aircraft fuel units per hour
"taxifuelflow": 0,
// taxi time in seconds
"taxitime": 600,
// trip fuel in aircraft fuel units
"tripfuel": 31.0976
},
// great circle distance in nautical miles, i.e. the direct line
// from departure to destination
"gcdist": 45.630123497407,
// initial altitude of the cruise segment, corresponds to speed/altitude
// group at the start of item15. For "VFR" as the cruise altitude, a
// low value will be returned
"initialaltitude": 6000,
// either "qnh" for local QNH or "std" for 1013.25hPa
"initialaltitudemode": "std",
// maximum cruise altitude within the flight plan
"maxaltitude": 6000,
// either "qnh" for local QNH or "std" for 1013.25hPa
"maxaltitudemode": "std",
// minimum fuel required by applicable regulations
"minfuelonboard": 58.411067708333,
// offblock time, in seconds since Unix epoch
"offblock": 1505933700,
// route distance in nautical miles
"routedist": 77.041501056212,
// fuel required for route
"routefuel": 30.6953125,
// time required in seconds
"routetime": 2067
}
List filed flight plans
To retrieve a list of all filed flight plans for the current user, use the following invocation
HTTP GET to https://api.autorouter.aero/v1.0/flightplan/file?offset=0&limit=10
Offset is the 0 based index of the first item to return and limit the number of items that may be returned. The response will look as follows:
{
// the total number of records that match the criteria (not the number returned)
"total": 2,
// array of records
"rows":
[
{
// the ID of the flight plan, used for all other APIs
"flightplanid": 2759,
// Eurocontrol IFPS flight plan ID
"ifplid": "AT04578792",
// details of the user that filed the plan
"name": "John",
"lastname": "Doe",
"email": "john.doe@pilot.com",
// Unix timestamp when the plan was created
"created": 1439891006,
// Unix timestamp of current off block time
"eobt": 1439927400,
// departure airport details
"departure": "EDTF",
"departurename": "Freiburg",
// destination airport details
"destination": "LSGG",
"destinationname": "Geneve",
// flight plan ICAO string
"fplan":"(FPL-ZZZZZ-ZG\n-C82R\/L -SDFGRY\/S\n-EDTF1950\n-N0147F100 OLBEN\/N0149F110 IFR N869 BENOT BENOT1R\n-LSGG0058\n-DOF\/150818 EET\/OLBEN0020 RMK\/CREW CONTACT +49170111111 PBN\/B2D2S1\n-E\/0740 P\/TBN R\/E A\/WHITE AND BLUE C\/DOE)",
// filing method, currently NMB2B or AFTN
"method": "NMB2B",
// filed route distance in nautical miles
"routedistance": 135,
// great circle distance in nautical miles
"gcddistance": 128,
// required route fuel in aircraft fuel units
"routefuel": 56.16015625,
// legal minimum fuel in aircraft fuel units
"minfuel": 80.5345703125,
// aircraft fuel unit ("l", "lb", "usgal")
"fuelunit": "l",
// see below for possible status values and state machine transisitions
"status": "filed",
"callsign": "ZZZZZ",
"aircraftdescription": "Cessna TR182 (1979)"
},
{
...
}
]
}
Optionally, the following parameters are supported:
- sidx
Order field, can be done of “eobt”, “filed”, “id”, “ifplId”, “routedistance”, “gcddistance”, “routefuel”, “status”, “callsign”. - order
“asc” for ascending and “desc” for descending. Default sort order is ascending. - search
Full text search string, matched in filer name, aircraft callsign and description, departure, destination aerodrome. - showclosed
Set to “yes” to include closed flight plans in the list.
Retrieve flight plan details
Apart from listing all flight plans, you can also request details of a specific flight plan:
HTTP GET to https://api.autorouter.aero/v1.0/flightplan/file/<flight plan id>
The return structure contains the same information as the list request above.
File flight plan
A flight plan is filed by modifying a route until it corresponds to the desired settings and issuing an API call:
HTTP POST to https://api.autorouter.aero/v1.0/flightplan/file/<route id>
The parameters are sent as JSON in the request body:
{
// ICAO flight plan string to be filed.
// Optional, if not specified, the flight plan stored in the route is used.
fpl: "(FPL-ZZZZZ-IG -P28R/L -SDFGBRY/S -EDDS0950 -N0138F090 ETASA4B ETASA DCT SUPIX T163 PSA PSA2L -EDDF0055 -DOF/160920 RMK/TOW:885 TOC:D14F090T0009 TOD:D92F090T0045 BOD:D108F004T0054 DAL:D111ADEDDF DAL:D38PTETASA DAL:D79PTPSA TAXI:7 PBN/B2D2 -E/0544 P/TBN R/E A/WHITE BLUE STRIPES)",
// structure containing configuration options for the briefing pack
// which will be generated and sent to the user
briefing:
{
// details see below: Briefing pack structure
},
// Array of additional AFTN addresses the flight plan should be sent to
// These addresses are taken in addition to the ones returned by the
// flight plan addressing engine
addresses: [],
// whether to skip the automatically determined AFTN addresses and only use the supplied ones
skipdefaultaddresses: false,
// whether to use GFS wind forecast data to calculate the enroute times
gfs: true,
// whether to force the flight plan into the system even when it does not validate
// Note: this should be used with caution!
force: false
}
A successful filing operation will return HTTP status code 200 and a JSON structure as follows:
{
// flight plan ID
"flightid": 2763,
// tracking key to build the tracking URL
"trackingkey": "L5ZS",
// whether the flight was queued for manual processing
"queued": false
}
If there was an error, a structure member named “error” will contain a description. The “queued” member is set to true when the flight was not acknowledged by Eurocontrol and sent to the manual correction queue. After some time (usually 10-20 minutes), the flight is either rejected or accepted and then the status changes accordingly. Note that only flight plans that don’t validate go to the manual correction queue. Unless the “force” parameter is given on the filing request, an error will be returned and the plan not filed.
Briefing pack structure
The briefing pack structure looks as follows:
{
"requested":
[
{
"type": "navlog",
"update": 1441785300
},
{
"type": "wb",
"update": 1441785300},
},
// ... items omitted ...
// external files follow
{
// digital flight plan for Garmin GNS430/530/G1000
"type": "garminfpl",
"update": 1441785300
},
{
// digital flight plan for Garmin GTN650/750/G3000
"type": "garmingfp",
"update": 1441785300
},
{
// digital flight plan for SkyDemon
"type": "skydemon",
"update": 1441785300
},
{
// AIP plates for the first alternate
"type": "alternate1plates",
"update": 0
},
{
// AIP plates for the second alternate
"type": "alternate2plates",
"update": 0
}
]
}
This contains the list of requested briefing pack items and additional external files. The briefing pack items are documented in the Briefing section. The field “update” contains a Unix timestamp at which an updated pack containing the given element should be produced. You can set it to zero for no update.
The external files are sent next to the briefing pack. If you pass an empty array, a briefing pack will not be created. Briefing packs can be requested independently at any times for filed flight plans and routes.
Delay flight plan
To delay a previously filed flight plan, use the following API:
HTTP POST to https://api.autorouter.aero/v1.0/flightplan/file/<id>/delay
With the new off block time in seconds since the Unix expoch as POST parameter “neweobt”. The call succeeded if the HTTP request returns code 200 and a valid JSON of the following form is returned:
{
"status": "success"
}
In case of failure, a JSON with the member “error” set to the cause is returned. Possible reasons for errors include but are not limited to:
- Communication problems with Eurocontrol, such as temporary network outages.
- The new EOBT is not within the valid timeframe (current time up to 5 days in the future).
- The new EOBT would move the plan inside the time window of another existing flight plan for the same callsign (overlapping flight plans).
- The filed route no longer validates with the new EOBT. Imagine you file a plan on a weekend going through a military exercise area and delay the plan to after the weekend when the airspace becomes unavailable.
- The flight plan was cancelled externally (by ATC or AIS and before autorouter was able to pick up the status change).
Cancel flight plan
To cancel a previously filed flight plan, use the following API:
HTTP POST to https://api.autorouter.aero/v1.0/flightplan/file/<id>/cancel
A HTTP POST parameter named “reason” should be passed with a descriptive reason of the cancel operation (e.g. “Weather worse than expected” or “Technical problem”). This is used for statistics.
Just like when delaying, a JSON with “status” set to “success” indicates a successful operation.
Bring forward flight plan
To move a previously filed flight plan to an earlier departure time, use the following API:
HTTP POST to https://api.autorouter.aero/v1.0/flightplan/file/<id>/bringforward
A HTTP POST parameter named “neweobt” should contain the new off block time in seconds since the Unix epoch. As the flight plan system does not have a notion of “bringing forward”, this operation actually cancels the flight plan and files an identical flight plan at the earlier time. This means the process takes more time than a delay and there are more reasons why it could fail. A success response looks as follows:
{
"status": "success",
// ID of the new flight plan
"flightid": 2762
}
An error occurred if either the HTTP return code is not 200 or the status field does not contain success. In this case, a field “error” with a description will be returned.
Send departure message
When departing from an uncontrolled aerodrome, it is the pilot’s responsibility to issue a departure message. Usually this is accomplished by asking ATC/FIS to open the flight plan once in the air and reporting the departure time.
In all of these cases, a station sends an “DEP” message over AFTN to the relevant parties referencing the flight plan and the arrival time. Without receiving an DEP message, AIS will not open the flight plan and there will be no search and rescue tracking. Also there might be difficulties dealing with ATC/FIS units along the route as the flight plan might not be available to them.
As an additional method, the autorouter API allows creating departure messages for flight plans filed through it. This API should be used with caution only as transmitting incorrect information can have adverse effects and compromise the safety of crews.
HTTP POST to https://api.autorouter.aero/v1.0/flightplan/file/<id>/departure
The POST parameter “timestamp” should be set to the Unix epoch time in seconds of the aircraft’s departure. The time can be up to 5 minutes in the future, 15 minutes in the past and up to 30 before or after the filed EOBT.
Send arrival message
When landing at an uncontrolled aerodrome, it is the pilot’s responsibility to issue an arrival message. This can be done in various ways, depending on the location. Traditional ways include:
- Ask ATC/FIS to close the flight plan shortly before commencing to land at the destination aerodrome.
- Perform a radio call to ATC/FIS via a remote communications outlet (RCO).
- Call AIS via phone after landing and transmit the landing time.
- Open an internet form of AIS to enter the landing time.
In all of these cases, a station sends an “ARR” message over AFTN to the relevant parties referencing the flight plan and the arrival time. Without receiving an ARR message, AIS will move the flight into the uncertainty case and start tracking down the whereabouts of the aircraft and crew.
As an additional method, the autorouter API allows creating arrival messages for flight plans filed through it. This API should be used with caution only as transmitting incorrect information can have adverse effects and compromise the safety of crews.
HTTP POST to https://api.autorouter.aero/v1.0/flightplan/file/<id>/arrival
The POST parameter “timestamp” should be set to the Unix epoch time in seconds of the aircraft’s arrival. The time must not be in the future and at maximum one hour in the past.
Flight plan status codes
The following status codes are defined for flight plans:
- created
The initial state of all flight plans, directly transitioning thereafter into either “filed” or “manual_correction. - filed
Flight plan is filed but not opened yet. - manual_correction
Flight plan went into the manual correction queue after filing, it will either be accepted (status: “filed”) or rejected (status “rejected”) after manual processing. - suspended
Flight plan was suspended by ATC/AIS. It will go back to the filed state after de-suspension (by ATC) or remain in the suspended state until closed. - departed
Flight departed. - terminated
ATC service for the flight was terminated. - arriving
Flight is in the terminal area of the destination aerodrome. - arrived
Flight arrived. - closed
Flight plan is closed (final state of all flight plans). - cancelled
Flight plan was cancelled. - rejected
Flight plan was rejected.
The following state diagram shows how the flight plan states can transition. Note the many possibilities how a flight state can go from departed to closed. This is due to the varying level of information of enroute ATC units.
Flight Plan Addressing Language APIs are documented here.