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.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 the METAR reports any liquid precipitation (drizzle, rain, or thunderstorms). The isIcy property is true if the METAR reports frozen precipitation (snow, snow grains, ice crystals, ice pellets, hail, or freezing rain) or if it is wet and the temperature is 0°C or below.
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 airport is in the airport database. Otherwise, magVar is not a number. 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 (see fetchAndSetPageWeather()). 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: {
				wkt: {dflt:'0'},
				wmps:{dflt:'0'},
			},
		},
		{id:'dep_windSpeedUnits', type:'unitSelector', unitClass:'depWindSpeed',
			dflt: 'wkt',
			options: [
				{value:'wkt', text:'kt.'},
				{value:'wmps', text:'mps.'},
			],
		},
		{id:'dep_metarText', type:'textOutput', multiline:true},
		{id:'dep_metarAge', 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_metarAge', '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 the airport ID is empty, then the instance is set to default conditions and the page is set from them without notices. If no METAR can be retrieved, then only a notice is posted (unless suppressed) and the page state variables are not changed. The distance from the station to search for nearby METARs is the maximum of acData.weatherRadius, acData.risk.areaImc, and acData.risk.areaLifr, with 20nm substituted for any that is unspecified. See the fetchMetar method. The results are set in pageId using the setPageWeather() method.

While the METAR is being fetched, the method calls startSpinner('metar') on the page (and stopSpinner('metar') when the fetch completes). This animates a RefreshButton component on the page that specifies spinner=metar. 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 80nm. is assumed. The search radius is set in the instance's weatherRadius property. If no METAR is found within NEARBY nautical miles, the Promise rejects. 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. If the airport is in the airport database, the instance's magVar is also set.

Parameters

Return value

A Promise. The Promise resolves to the Metar instance and rejects to an Error('failure') instance.

setDflt()

setDflt()

Set the Metar instance to default conditions: Clears the station IDs, text, and field errors, and sets isFetched to false, weatherRadius to 80nm, the wind to 360° at 0 'wkt', the altimeter and temperature to standard sea level conditions, the ceiling and visibility to unrestricted, the flight category to '', and magVar to undefined.

Return value

The Metar instance.

setPageWeather()

setPageWeather(pageId)
setPageWeather(pageId, noNotice)

Sets the state variables in pageId from the instance's data. If the airport ID is set and magVar is not a number, it will also post a notice asking the user to adjust the wind direction. 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 in feet from the most recently fetched METAR or 99,900 if there is no ceiling or no valid fetched METAR.

distance

The distance, in nautical miles, from stationId to fetchedId. It is set only when a METAR is fetched.

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.

isWet

True if the fetched METAR indicates liquid precipitation (drizzle, rain, or thunderstorms), regardless of temperature.

magVar

The magnetic variance of stationId (not fetchedId), rounded to the nearest 10°. The magVar value is added to a magnetic north direction to convert to true north. It is set only if stationId is in the airport database; otherwise, it is not a number (use isNumber() to test). setDflt() resets it to undefined.

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 'wkt' (knots) or 'wmps' (meters per second).

Static properties

Metar.NEARBY

The same value is also available as the exported constant NEARBY from metar.js.
The distance, in nautical miles (20), 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.