Airport Database Reference

Related documents

• MVCS index
• Storage Reference
• OutsideConditions Reference

Rable of contents

• Introduction
  • Airport codes
  • Runway surfaces
  • Airport database sources
  • Airport database structure
  • Building the airport database
  • Airport database updates
  • Creating an Airport instance
  • Pages and runway performance
  • Computing runway performance
• Constructor
• Instance methods
  • setAirport()
  • runwayOptions()
  • setPageAirportInfo()
  • setPageRunwayPerformance()
• Static methods
  • Airport.checkDbUpdate()
  • Airport.drawRunway()
  • Airport.fetchDbUpdate()
  • Airport.findAll()
  • Airport.hasData()
  • Airport.hasDbUpdate()
  • Airport.lookup()
  • Airport.renderAirportRows()
• Properties
  • Airport.minRunwayLength
  • Airport.surfaces

Introduction

The airport database contains airport and runway information. It is built into the app but can be updated via the Internet. The arpt page controls the airport database and is responsible for loading and updating the database.

Individual airport information is accessed using an instance of the Airport class. An Airport instance contains information about the airport itself, such as ID codes, location, elevation, and information about each usable runway, such as ID, width, TORA, LDA, slope, and surface type. Runways not usable for this aircraft type are deleted from the database. For example, runways that are too short or of an unsupported surface type (e.g., water). Airports that don't have any usable runways are deleted from the database.

Airport codes

Airports can have several identification codes. For example, they can have normal 4-letter codes where the first letter identifies a region (e.g., KSFO), 3-letter IATA codes (e.g., SFO), regional codes (e.g., O22), or informal codes (e.g., GB-0002). Some codes in different regions can conflict. In that case, the code for the smaller airport is removed from the database. If all of an airport's codes are eliminated, the airport is deleted from the database.

Runway surfaces

Runway surfaces are quite varied. Since performance is the only issue, not weight-bearing, the surfaces are classified into the following categories:

• 'hard'
  A hard, smooth surface, usually composed of concrete or asphalt.
• 'turf'
  A grass surface. If the height of the grass is excessive, an additional performance penalty may be required.
• 'dirt'
  A hard dirt surface.
• 'gravel'
  A gravel surface. Hard-surface runways in poor condition are classified as gravel.
• 'water'
  A lake, river, ocean, or other waterway.

Different models and options combinations can have different surface requirements. For example, an aircraft with floats installed will want to use water runways, but models without will not. The type-wide data can set the validRunwaySurfaces property with an array of valid surface codes, and individual models or options can override this list. Runways not on the validRunwaySurfaces are not considered when setting up the usable runway options.

Airport database sources

The airport database relies on two sources:

• The NFDC airport database
  The NFDC database is the primary database for the United States and US Territories. The legacy format APT.txt file must be manually downloaded to source/airportData/NFDC. You may choose the current data or the preview that will be made current at the next database cycle.
• ourairports.com
  Ourairports.com (OADC) is a crowd-sourced database that provides airport information for airports not covered by the NFDC. Anyone can register and add or edit airport data. If the NFDC database has an airport, the NFDC information overrides the OADC data. However, the OADC information can be used to add codes to an NFDC airport. If codes conflict with NFDC information, the NFDC information is used for that code. The Makefile automatically downloads the latest OADC database every time the airport database is built.

Airport database structure

The airport database source/app/${app}/airportData.json is a JSON-encoded object with the following properties:

• version
  The version of the airport data format. Currently "1".
• timestamp
  A JSON-encoded date string indicating the time the database was built.
• minRunwayLength
  The minimum runway length accepted in this database.
• airportFields
  An array of strings for the names of each index in an airport entry array. The fields for version 1 are, in order:
  • codes
    This index's corresponding airport entry element contains a string of comma-separated airport codes identifying this airport.
  • latitude
    This index's corresponding airport entry element contains decimal latitude.
  • longitude
    This index's corresponding airport entry element containss decimal longitude.
  • elevation
    This index's corresponding airport entry element contains the airport elevation in feet.
  • runways
    This index's corresponding airport entry element contains an array of runway entries. Each runway entry is an array with fields named by the runwayFields property.
• runwayFields
  An array of strings for the names of each index in the runway entry array. The fields for version 1 are, in order:
  • id
    The runway ID string.
  • trueDir
    The runway direction, in degrees relative to true North.
  • width
    The runway width, in feet.
  • slope
    The runway slope, in percent (rise/run).
  • tora
    The runway Takeoff Runway Avaialable (TORA), in feet.
  • lda
    The runway Landing Distance Avaialable (LDA), in feet.
  • surface
    The runway surface string.
• airports
  An array of airport entries. Each entry is an array instead of an object to compact the database. The meaning of each index in an entry is determined by the contents of the airportFields array.

Building the airport database

The airport database itself is built by the buildAirportDB.js nodeJS script. The script outputs the airport database as a JSON-encoded object. The script takes the following flags:

• -l [len] or --length [len]
  Sets the minimum runway length [len] in generated database. Runways less than this length are deleted. Defaults to 1,500 ft.
• -h or --hard
  Include only hard surface runways in generated database.
• -t or --turf
  Include only hard and turf surface runways in generated database.
• -d, --turf
  Include only hard, turf, and dirt surface runways in generated database.
• -w or --water
  Add water runways in generated database. By default no water runways are included.
• -v or --verbose
  Verbose mode.
• -L or --log
  Send log output to the .
• -o or --output
  Send the database output to the .
  Each app can have a unique setting of the flags in source/airportData/dbFlags/${app}.txt.

To build the database first manually download the APT.txt file for the current or next version of the NFDC airport database to source/airportData/NFDC. After that run make -B db, which does the following:

• Downloads the current ourairports.com database.
• Runs buildAirportDB.js with the flags in source/airportData/dbFlags/${app}.txt and outputs the result to source/app/${app}/airportData.json.
• Builds source/app/${app}/airportDataTimestamp.json which contains a JSON-encoded object with two properties:
  • version
    A timestamp file version number, Currently '1'.
  • timestamp
    A JSON-encoded date string
• Copies the contents of source/app/${app}/airportData.json prepended with:

export const airportData =

to source/app/${app}/buildStamp/data/airportData.js. This file is loaded by commonaero/airport.js to access the built-in database by importing airportData.

Airport database updates

The app may have a dynamically updated database in addition to the built-in database. When the app starts up or is resumed after a prolonged period of inactivity (>1 day), the app fetches the airportDataTimestamp.json file from the origin server. It compares the timestamp in the JSON-encoded object to the timestamp field in the current database. If it's different, then the app fetches airportData.json. The update is stored in the device's local Object storage under the key 'airportDb'. The updated database is then used in place of the built-in database.

Creating an Airport instance

The Airport constructor takes an airport code, airportId, as an argument. The instance contains properties and methods for accessing and using the airport data. The airport can be changed subsequently by calling the setAirport() method.

The Airport instance contains the following properties:

• airportId
  The airport code that was used to look up the airport.
• codes
  An array containing all the airport's codes.
• elevation
  The airport elevation, in feet.
• hasData
  True if airportId found data in the database.
• latitude
  The airport latitude, in decimal degrees.
• longitude
  The airport longitude, in decimal degrees.
• magVar
  The airport's magnetic variance, in degrees.
• magVarR
  The airport's magnetic variance, rounded to the nearest 10 degrees.
• runwayIds
  An array containing all the usable runways.
• runways
  • id
    The runway ID.
  • lda
    The runway Landing Distance Avaialable (LDA), in feet.
  • magDir
    The runway direction, in degrees relative to magnetic North.
  • slope
    The runway slope, in percent (rise/run).
  • surface
    The runway surface string.
  • tora
    The runway Takeoff Runway Avaialable (TORA), in feet.
  • trueDir
    The runway direction, in degrees relative to true North.

If the database does not contain data associated with airportId, then the instance provides default airport information with no runways and hasData will be false.

Pages and runway performance

Some Airport instance methods work with other pages containing airport information and compute takeoff and landing performance (e.g., the Departure or Destination pages). The methods have a pageId argument for pages containing these common airport state variables:

• ${pageId}_airportCode
  The main code string for the airport user output.
• ${pageId}_airportId
  The airport code user input.
• ${pageId}_airportMsg
  The message user output for the airport.
• ${pageId}_bestRunwayId
  The best runway user output.
• ${pageId}_crosswind
  The crosswind wind speed user output.
• ${pageId}_crosswindDir
  The crosswind wind direction string user output.
• ${pageId}_crosswindMsg
  The crosswind message user output.
• ${pageId}_elevation_ft
  The airport elevation user input.
• ${pageId}_hasAirportData
  The internal boolean indicating the database contains valid data for the airport.
• ${pageId}_headwind
  The headwind wind speed user output.
• ${pageId}_magVar
  The magnetic variance user output.
• ${pageId}_obstacle_ft
  The obstacle clearance distance user output.
• ${pageId}_roll_ft
  The ground roll user output.
• ${pageId}_rollAdjustment
  The additional ground roll adjustment, in percent, for runway conditions that have no performance data in the POH.
• ${pageId}_runwayCondition
  The runway surface condition user input: dry, wet, or icy.
• ${pageId}_runwayId
  The runway ID user output.
• ${pageId}_runwayLeft_ft
  The runway remaining user output.
• ${pageId}_runwayLeftMsg
  The runway remaining message user output.
• ${pageId}_runwayLength_ft
  The runway length user input.
• ${pageId}_runwayMagDir
  The runway magnetic heading user output.
• ${pageId}_runwayObstacleDist_ft
  The distance from the AER or DER to check for obstacles user output.
• ${pageId}_runwaySlope
  The runway slope user input.
• ${pageId}_runwaySurface
  The runway surface category user input.
• ${pageId}_runwaysText
  The list of usable runways user output.
• ${pageId}_runwayWidth_ft
  The runway width user output.
• ${pageId}_safeObstacle_ft
  The runway safe obstacle clearance distance user output.
• ${pageId}_safeRunwayLength_ft
  The runway safe runway length user output.
• ${pageId}_selRunway
  The selected runway user input.
• ${pageId}_userRollAdjustment
  The additional ground roll adjustment, in percent, that the user can set to allow for unusual conditions like long grass or a soft field.
• ${pageId}_windDir
  The wind direction user input.
• ${pageId}_windDir
  The wind direction user input.

In addition, Airport instances also require the following state variables:

• set_tkoSafetyFactor
  A user input for the takeoff safety factor in percent. This defaults to 50.
• set_ldgSafetyFactor
  A user input for the landing safety factor in percent. This defaults to 50.
• set_obsSafetyFactor
  A user input for the obstacle clearance distance safety factor in percent. This defaults to 15.
• set_noHeadwind
  A user input checkbox indicating whether the displayed runway performance should not include any headwind component as an added safety factor.

The setPageAirportInfo() method sets the specified pageId state variables based on the information in the Airport instance. It sets the airport elevation, magnetic variance, runway options, and the selected runway's length, width, slope, and surface.

Computing runway performance

The setPageRunwayPerformance() method computes the performance of all usable runways, picks the best, and then sets the results for the selected runway (the best or a specific runway from ${pageId}_selRunway) in the pageId state variables. The setPageRunwayPerformance() is passed a distanceFn argument containing an aircraft-specific function to compute the ground roll and obstacle clearance distance for each runway.

Non-POH performance adjustments

The POH typically does not specify performance under all conditions. For example, it often fails to provide adjustments for wet runways or runway slope. The app can allow the user to specify a set of standard ground roll adjustments based on runway surface and condition. The standard adjustments are for hard, wet runways, icy or snow-covered runways, unpaved runways, or runway slope. In some cases, the standard adjustments need adjusting. For example, for longer grass or soft conditions on a turf runway.

The distanceFn also computes a rollSurfaceFactor that contains the non-POH adjustment factor to the POH-derived roll. The setPageRunwayPerformance() method sets the ${pageId}_rollAdjustment output state variable to let the user know the non-POH adjustment used in the calculations. The user can add an additional factor for actual conditions (e.g. long grass or a soft field) by setting the ${pageId}_userRollAdjustment input state variable. The different is roll due to this factor is computed and added to the published ground roll, obstacle clearance, and safe distances.

Safe runway

The computation includes the "safe" runway distances. The ground roll and obstacle clearance distances are based on a safety factor in the set_tkoSafetyFactor or set_ldgSafetyFactor state variables. However, the minimum safe runway can be no less than the no-headwind obstacle clearance distance. This is to provide the required height above the DER or AER for IFR procedures. In addition, the runway is not safe the crosswind exceeds the maximum crosswind published in the POH.

Best runway

The best runway is selected after the performance of all usable runways is computed. The selection is based on the following criteria in order of priority:

• A runway with a hard surface is preferred over other surfaces.
• A runway within the safe runway criteria is preferred over non-safe runways.
• The runway with the shorter ground roll, taking into account wind, slope, and runway surface, is preferred.
• A longer runway is preferred over a shorter runway.

The best runway calculation is unaffected by the value in the ${pageId}_userRollAdjustment state variable. It only applies to the published values for the selected or best runway.

Constructor

syntax

new Airport(airportId)

The constructor uses the setAirport() method to retrieve the information for airportId from the database and set the instance properties.

Parameters

• airportId
  An airport ID string

Instance methods

setAirport()

setAirport(airportId)

This method sets the airport ID for the Airport instance to airportId and retrieves the airport information from the database. If acData.validRunwaySurfaces is present, then runway surfaces not included in the acData.validRunwaySurfaces array will not appear in the instance's runway list.

Parameters

• airportId
  An airport ID string

runwayOptions()

runwayOptions()

Returns an array of options given an array of runway ID strings. If the airport has no data or the ID is null, it returns an array containing all IDs from 01 to 36.

This method is used to set the runway ID options in the ${pageId}_selRunway state variable.

Return value

An array of runway ID strings.

setPageAirportInfo()

setPageAirportInfo(pageId)

This method sets the airport-related state variables according to the instance properties. The affected state variables are:

• ${pageId}_airportCode
  Set to the main code string for the airport.
• ${pageId}_airportMsg
  Set to a message alerting the user if the airport ID in not in the database.
• ${pageId}_elevation_ft
  Set to the airport elevation, in feet. The input is disabled if the database has the airport data.
• ${pageId}_hasAirportData
  Set to true if the database contains valid data for the airport.
• ${pageId}_magVar
  Set to the magnetic variance in degrees.
• ${pageId}_runwaySlope
  Set to the runway slope in percent. The input is disabled if the database has the airport data.
• ${pageId}_runwaysText
  Set to a comma-separated list of usable runways..
• ${pageId}_selRunway
  Set the selector options to the usable runways. Include a "Best" option that is the default value.
• ${pageId}_windDir
  Set the magVar property so that the wind direction can be converted between magnetic north and true north as required.

Parameters

• pageId
  A page ID string

setPageRunwayPerformance()

setPageRunwayPerformance(pageId, conditions, distanceFn)

This method computes the performance of all usable runways for the conditions, picks the best, and then sets the results for the selected runway (the best or a specific runway from ${pageId}_selRunway) in the pageId state variables.

conditions is an OutsideConditions instance representing the current OAT and other weather conditions. distanceFn is function that takes an OutsideConditions instance as an argument. The instance also contains the following properties:

• runwayCondition
  The runway condition string: dry, wet, icy.
• runwaySlope
  The runway slope in percent.
• runwaySurface
  The runway surface code: hard, turf, dirt, gravel, water.
• headwind
  The headwind for the runway direction, in knots. Negative numbers are tailwinds.
• crosswind
  The crosswind for the runway direction, in knots. Negative numbers are from the left.
  The distanceFn() returns an object containing the following properties:
• roll
  The computed grouns roll for the runway and conditions.
• obstacle
  The computed obstacle clearance distance for the runway and conditions.

The method clones the conditions instance and then iterates over all the usable runways, doing the following:

• Sets headwind and crosswind properties in the cloned conditions instance to the headwind and crosswind for that runway.
• Sets runwaySlope, runwaySurface, and runwayCondition properties in the cloned conditions instance to the runway slope, surface category, and surface condition (dry, wet, or icy).
• Calls the distanceFn function with the cloned conditions instance with the added information as an argument. The function returns an object containing the computed performance results for that runway and conditions.
• Calls the distanceFn function again with the cloned conditions instance with any headwind set to zero as an argument. Tailwinds are not set to 0.
• Given the results from calling distanceFn(), it computes the "safe" runway length and includes the ground roll safety factors.
  Once the performance of all runways is computed, the method will pick the best runway according to the above criteria.

The ${pageId}_selRunway state variable can have a value of "Best", in which case the performance from the best runway is set in the page's state variables. If the value of ${pageId}_selRunway is a specific runway, then the computed data from the selected runway is set. In either case, the value of ${pageId}_bestRunwayId is set to the selected best runway. The selected runway's performance is then adjusted by the difference in ground roll due to the setting of the ${pageId}_userRollAdjustment state variable.

The selected runway's performance is set into the following state variables:

• ${pageId}_crosswind
  The crosswind wind speed user output.
• ${pageId}_crosswindDir
  The crosswind wind direction string user output.
• ${pageId}_crosswindMsg
  The crosswind message user output.
• ${pageId}_headwind
  The headwind wind speed user output.
• ${pageId}_obstacle_ft
  The obstacle clearance distance user output.
• ${pageId}_roll_ft
  The ground roll user output.
• ${pageId}_rollAdjustment
  The additional ground roll adjustment, in percent, user input.
• ${pageId}_runwayId
  The runway ID user output.
• ${pageId}_runwayLeft_ft
  The runway remaining user output.
• ${pageId}_runwayLeftMsg
  The runway remaining message user output.
• ${pageId}_runwayLength_ft
  The runway length user input.
• ${pageId}_runwayMagDir
  The runway magnetic heading user output.
• ${pageId}_runwayObstacleDist_ft
  The distance from the AER or DER to check for obstacles user output.
• ${pageId}_runwaySlope
  The runway slope user input.
• ${pageId}_runwaySurface
  The runway surface category user input.
• ${pageId}_runwaysText
  The list of usable runways user output.
• ${pageId}_runwayWidth_ft
  The runway width user output.
• ${pageId}_safeObstacle_ft
  The runway safe obstacle clearance distance user output.
• ${pageId}_safeRunwayLength_ft
  The runway safe runway length user output.

Parameters

• pageId
  A page ID string

Static methods

Airport.checkDbUpdate()

Airport.checkDbUpdate(airportId)

Initiates a check for an airport DB update. If there's an update, it will fetch it and update the internal airport database.

Airport.drawRunway()

Airport.drawRunway(canvas, pageId)

Draws a runway diagram with relative headwind and crosswind shown. It also shows the ground roll and safe runway distances as colored zones on the runway surface.

The pageId is that page ID to get the standard runway performance state variables to use to create the diagram.

Parameters

• canvas
  A <canvas> element to draw the diagram on.
• pageId
  A page IS string to use as a prefix for the standard aircraft performance state variables. See Pages and runway performance.

Airport.fetchDbUpdate()

Airport.fetchDbUpdate()

Returns a Promise that resolves when the updated database has been fetched and the results have been successfully stored in local object storage. See Airport database updates and Object storage.

Return value

A Promise.

Airport.findAll()

Airport.findAll(airportId, radius)

Find all airports within radius (in nm) of airportId. Returns an array of airport ID strings sorted in order of distance.

Parameters

• airportId
  An airport ID string.
• radius
  A distance, in nautical miles from airportId to search for airports.

Return value

An array of airport ID strings sorted in order of distance. If no airports are found or if airportId is not in the database, and empty array is returned.

Airport.hasData()

Airport.hasData(airportId)

Returns true if there's data associated with airportId in the database.

Parameters

• airportId
  An airport ID string

Return value

A boolean.

Airport.hasDbUpdate()

Airport.hasDbUpdate()

Return a Promise that resolves with a boolean that's true if the server has an updated database. The method fetched only the small timestamp file, not the large database file. See Airport database updates.

Return value

A Promise.

Airport.lookup()

Airport.lookup(airportId)

Lookup an airport ID in the airport database. Returns an object with properties set according to the field names and values in the database. See Airport database structure.

Parameters

• airportId
  An airport ID string

Return value

A object.

Airport.renderAirportRows()

Airport.renderAirportRows(pageId, metar)

Returns a template with an array of card rows Cr Components containing the user input and outputs for airport and runway information on all airport-related pages (Departure, Departure return, Destination, Alternate). Uses the standard airport state variables, see Pages and runway performance.

This method is used by airport-related pages to keep the airport information in a standard format.

Parameters

• pageId
  A page ID string
• metar
  A Metar instance that's associated with pageId. This is only used to implement the refresh button.

Return value

A Template containing airport information <Cr> components.

Properties

Airport.minRunwayLength

The minimum runway length accepted in the current airport database. Shorter runways are deleted as are airports without any acceptable runways.

Airport.surfaces

An array of surface category strings. The possible strings are:

• 'hard'
  Hard surfaces that are not in poor or failed condition.
• 'turf'
  Turf, grass, or sod.
• 'dirt'
  Dirt.
• 'gravel'
  Gravel or hard surfaces in poor or failed condition.
• 'water'
  Water.