Metar reference

Table of contents

Introduction

A Metar instance fetches, decodes, and stores the information in a METAR associated with a METAR station (usually an airport). here's an example:

// fetch the conditions for lax
const metar = new Metar()
metar.fetchMetar('KLAX', 10).then(() => {
	console.log(`wind speed = ${metar.windSpeed}`);
	console.log(`airport fight category = ${metar.this.flightCategory}`);
});

The [fetchMetar() method] returns a Promise. When the Promise resolves, the Metar instance contains properties set to the decoded information in the METAR text. If the Promise is rejected, the properties are set to default values. The second parameter is a maximum radius, in nautical miles from the given airport, to search for a valid METAR and area conditions.

If a METAR is fetched successfully, the isfetched property will be true. If the METAR has missing fields, strings for the missing fields will be in the fieldErrors array.

Here's a list of information properties in the instance that contain decoded METAR values:

Station ID

The stationId property will contain the ID used to look up the METAR. This may not be the ID string passed to the [fetchmetar() method] as the method will substitute the airport's primary GPS ID, if available. The fetchedid is the nearest available METAR to the given airport. If the airport does not have a published local METAR, the stationId and fetchedid will be different.

Computed properties

Several useful values are also computed from the METAR data:

The isWet property is true if there's precipitation and the temperature is above zero. Similarly, the isIcy is true if there's precipitation and the temperature is below zero.
The flightCategory contains the normal flight conditions category: VFR, MVFR, IFR, and LIFR. The betterConditions property contains an array of objects containing information about nearby stations with better conditions. Each object contains a station ID, distance from the initial station ID, and flight category. Lastly, the magnetic variance at the stationId location is provided in magVar if the location is known. If the location is unknown, the isValidMagVar property is false. The magnetic variance can be used to convert the wind direction(s) from true north to magnetic north since all METAR wind directions are relative to true north.

Page methods

METARs are mostly associated with airports, and app pages that specify airports like the Departure, Destination, and Alternate airport pages, all require the same METAR information. The Metar class has two methods that set a standard set of state variables on a given page: The setPageWeather() method and the fetchAndSetPageWeather() method. The setPageWeather() method sets a page's weather-related state variables from a Metar instance. and the fetchAndSetPageWeather() method primarily calls the fetchMetar() method with the page's airport ID and then calls the setPageWeather() method. In addition, it causes the METAR refresh button to animate while the fetch is in progress. Here's an example:

const depMetar = new Metar();

ctl.createPage({
	pageId: 'dep',
	title: 'Departure',
	// page state variables
	stateVarInfo: [
		// aircraft independent inputs
		{id:'dep_airportId', type:'textInput',
			allCaps:true, maxLength:7, dflt:'',
			onUserChange: (sVar, value) => {sVar.value = value.trim().toUpperCase();},
		},
		{id:'dep_elevation_ft', type:'numericInput',
			fmt:'-5', min:-2000, max:11000, dflt:0, incr:100, tw:'??,|???|ft.'
		},
		{id:'dep_altimeter', type:'unitInput', unitClass:'depAltimeter',
			units: {
				inhg: {fmt:'2.2', min:28, max:30.99, incr:0.01, tw:'??.|?|?|in.', dflt:29.92},
				hpa: {fmt:'4', incr:1, tw:'??|?|?|hPa.'},
			},
		},
		{id:'dep_altimeterUnits', type:'unitSelector', unitClass:'depAltimeter',
			dflt:'inhg',
			options: [
				{value:'inhg', text:'in.'},
				{value:'hpa', text:'hpa.'},
			],
		},
		{id:'dep_oat', type:'unitInput',
			dflt: 'dC',
			units: {
				dC: {fmt:'-2', min:-60, max:60, dflt:15, tw:'??|°C'},
				dF: {fmt:'-3'},
			},
		},
		{id:'dep_windDir', type:'windDirInput', unitClass:'depWindDir'
			magVar: 0,
			units: {
				M: {dflt:'010'},
				T: {dflt:'010'},
			},
		},
		{id:'dep_windDirUnits', type:'unitSelector', unitClass:'depWindDir'
			dflt: 'M',
			options: [
				{value:'M', text:'Mag.'},
				{value:'T', text:'True'},
			],
		},
		{id:'dep_windSpeed', type:'windSpeedInput', unitClass:'depWindSpeed',
			units: {
				kt: {dflt:'0'},
				mps:{dflt:'0'},
			},
		},
		{id:'dep_windSpeedUnits', type:'unitSelector', unitClass:'depWindSpeed',
			dflt: 'kt',
			options: [
				{value:'kt', text:'kt.'},
				{value:'mps', text:'mps.'},
			],
		},
		{id:'dep_metarText', type:'textOutput', multiline:true},
		{id:'dep_metarAgeText', type:'textOutput', multiline:true},
		{id:'dep_flightCategory', type:'textOutput'},		// LIFR,IFR,MVFR,VFR
		{id:'dep_magVar', type:'textOutput', fmt:'3', dflt:0},
		...
	],
	computeInfo: [
		{
			title: 'metar',
			inputs: ['dep_airportId', 'arpt_db'],
			outputs: [
				'dep_metarText', 'dep_metarAgeText', 'dep_flightCategory', 'dep_areaConditions',
				'dep_magVar',
			],
			fn: () => {
				// fetch the METAR and set page data
				depMetar.fetchAndSetPageWeather('dep');
			}
		},
		...
	],
	...
});

METAR source

METAR data is retrieved using the aeroServer.getMetar() server API. This ultimately retrieves the data from aviationweather.gov. Using the server API insulates the app code from the data source.

Constructor

syntax

new Metar()

Constructs a new Metar instance. The new instance's properties are set to standard conditions. See the setDflt() method.

Instance methods

fetchAndSetPageWeather()

fetchAndSetPageWeather(pageId)
fetchAndSetPageWeather(pageId, noNotice)

Fetched the nearest METAR to the station specified by the ${pageId}_airportId state variable and set the weather on the page specified by pageId from the resulting instance settings. If no METAR is available, then the page is set to standard conditions. The distance from the station to search for nearby METARs is acData.weatherRadius or 40nm, if unspecified. See the fetchMetar method. The results are set in pageId using the setPageWeather() method.

The method will look for an element with the class name metarRefresh within the page (i.e., a descendant of an element with a class name containing the pageId) and add the metarSpin class name to it while the METAR is being fetched. If it exists, this will cause the element contents to rotate. This is normally the METAR refresh button.

The method will limit the re-fetching of METARs to once per minute. If a request comes in within that time, it will set the page to the previously fetched results.

Parameters

fetchMetar()

fetchMetar(stationId)
fetchMetar(stationId, distance)

Returns a Promise to fetch and decode the METAR associated with stationId. The Promise resolves to the Metar instance and rejects to an Error instance. If stationId does not publish a METAR and stationId is an airport ID that's in the airport database, the METAR for the nearest available METAR within distance is returned. If distance is not provided, then 40nm. is assumed. The search radius is set in the instance's waetherRadius property. The instance's fetchedId property will be set to the METAR station ID that was fetched.

If stationId is an airport ID, then an alternate code may be substituted. The instance's stationId property will be set to the actual ID used.

Parameters

Return value

A Promise. The Promise resolves to the Metar instance and rejects to an Error instance.

setDflt()

setDflt()

Set the Metar instance to default conditions. Sets the altitude, altimeter, and temperature to standard sea level conditions.

setPageWeather()

setPageWeather(pageId)
setPageWeather(pageId, noNotice)

Sets the state variables in pageId from the instance's data. If some METAR fields were unable to be decoded, it will post a user notice explaining which fields were not decoded and have been set to default values. If noNotice is truthy then the notice is suppressed.

Here's a list of required state variables and how they are set:

Parameters

Instance properties

age

The current age of the most recently fetched METAR in minutes.

altimeter

The altimeter setting from the most recently fetched METAR or the value for standard conditions.

altimeterUnits

The units for the altimeter setting from the most recently fetched METAR or inHg.

betterConditions

An array of objects containing information on stations within weatherRadius that are reporting better conditions than the fetchedId. The array is in order of distance from stationId. The array will be empty if the fetchedId reports VFR conditions or if no better conditions are found. Otherwise, only stations reporting better conditions than the fetchedId or previous stations in the array are included. This means that the array will contain a maximum of three elements, for IFR, MVFR, and VFR, and the maximum may be achieved only when the fetchedId reports LIFR conditions.

Each object in the array contains the following properties:

ceiling

The computed ceiling from the most recently fetched METAR

fetchedId

The station ID from the most recently fetched METAR. This is the METAR nearest to the location of stationId.

fieldErrors

An array of METAR field strings for the METAR fields could not be decoded.

flightCategory

The computed flight category for the data in the most recently fetched METAR. Can be:

isfetched

True if a METAR has been successfully fetched. If false, the other data fields are set to standard conditions.

isIcy

True if the fetched METAR indicates frozen precipitation or if it indicates liquid precipitation and the OAT is 0°C or below.

isValidMagVar

True if the magVar field has been set to a valid value. This is only true if the stationId is in the airport database and the location is known.

isWet

True if the fetched METAR indicates liquid precipitation.

magVar

The magnetic variance of stationId (not fetchedId). The magVar value is added to a magnetic north direction to convert to true north.

oat

The outside air temperature from the most recently fetched METAR or 15 if there is no valid fetched METAR.

stationId

The station ID that was used to request the METAR. This may differ from the ID used in the fetchMetar() request if the airport database has an equivalent ID that's better.

text

The text of the most recently fetched METAR.

time

The time in milliseconds from January 1, 1970, from the most recently fetched METAR.

visibility

The visibility in statute miles from the most recently fetched METAR or 99 if there is no valid fetched METAR. If the visibility in the METAR was in meters, then the value is converted to statute miles.

weatherRadius

The distance, in nautical miles, from the stationId to search for the weather conditions nearby.

windDir

The wind direction in degrees from true north from the most recently fetched METAR or 360 if there is no valid fetched METAR or the wind direction is VRB.

windDir2

The second variable wind direction in degrees from true north from the most recently fetched METAR or 360, if there is no valid fetched METAR or the METAR wind direction is VRB. If the wind direction is not variable, this is set to the same value as windDir.

windDirStr

The wind direction string from the most recently fetched METAR.

windGust

The wind gust in windSpeedUnits from the most recently fetched METAR or 0 if there is no valid fetched METAR. If the wind speed does not have a gust, this is set to the same value as windSpeed.

windSpeed

The wind speed in windSpeedUnits from the most recently fetched METAR or 0 if there is no valid fetched METAR.

windSpeedStr

The wind speed string from the most recently fetched METAR.

windSpeedUnits

The wind speed units from the most recently fetched METAR. This may be 'kt' or 'mps'.

Static properties

Metar.NEARBY

The distance within which METARs from other airports will be substituted if the airport
METAR is not available.

Static methods

Metar.decode()

Metar.decode(text)

Returns an object that contains the decoded fields of the METAR string in text. It the decoded fields are:

Parameters

Return value

An object containing the decoded METAR values or null if text has no content.