ForecastWeather reference

Related documents

• MVCS index
• Aeronautical Server API and reference
• Aeronautical Utilities Reference
• Airport Database Reference
• Open-Meteo forecast API

Table of contents

• Introduction
  • Route offsets
  • Data source and validity
  • Errors
• Importing
• getForecastWeather()
• Constructor
• Instance methods
  • fetch()
  • getAltimeterAt()
  • getAverageAltimeter()
  • getAverageFreezingLevel()
  • getAverageHeadwind()
  • getAverageTemperature()
  • getEffectiveHeadwind()
  • getFreezingLevelAt()
  • getTemperatureAt()
  • getWindAt()
  • isExpired()
  • isFresh()
  • isValid()
• Instance properties
  • age
  • distance
  • error
  • timestamp
  • waypoints

Introduction

A ForecastWeather instance holds forecast weather data for a route of one or more points, and provides the forecast winds, temperatures, freezing level, and altimeter setting at any altitude and position along the route. It is used to compute enroute winds, headwinds, and temperatures.

A ForecastWeather instance is created for a route that is either a single point or a series of points. Forecast data is fetched for a series of waypoints spaced along the route, no more than about 100 nm apart, and values between the waypoints are linearly interpolated. Winds are vector averaged. Values at altitudes between the forecast pressure levels are interpolated, and values above or below the highest or lowest pressure level use the data from that level.

Normally, instances are not created directly. Use getForecastWeather(), which finds the airports, shares and caches instances, and fetches the data.

Route offsets

Many methods have an offset argument that specifies a position along the route as a distance in nautical miles from the departure (the first route point). For the methods that return values at a point, a negative offset (including -0) is measured back from the end of the route (the destination), so -0 is the destination. For the methods that return an average over a distance, offset is the distance from the departure and distance is the length of the route portion to average over, in nautical miles; distance defaults to the whole route.

When the route is a single point, the offset is ignored and the data at that point is used.

Data source and validity

The forecast is fetched using aeroServer.fcstWeather() from the Open-Meteo forecast API. For each waypoint, the following are fetched for the current forecast hour:

• The wind speed, wind direction and temperature at the 1000, 850, 700, 600, 500, 400, 300, 250, and 200 hPa pressure levels. These are converted to pressure altitudes using the standard atmosphere.
• The surface pressure, which is converted to an altimeter setting using the elevation of the waypoint.
• The freezing level height.

When a method has a date argument, the forecast hour closest to date is used.

Fetched data is considered to be:

• fresh for 1 hour after it is fetched. A fetch() of fresh data does nothing.
• valid for 6 hours after it is fetched. Methods return null (or the standard altimeter setting) if the data is not valid.

Errors

The methods that return forecast values return null if no valid data is available or if the data does not contain a usable value. The exceptions are the altimeter methods, which return the standard altimeter setting (STD_ATM_HG), and the headwind methods, which return 0.

Importing

getForecastWeather() and ForecastWeather are available for import from common/aero/export.js.

getForecastWeather()

Syntax

getForecastWeather(id)
getForecastWeather(id1, id2)

Returns a Promise for a ForecastWeather instance with current forecast data for an airport, or for the route between two airports. The airports are found using Airport.lookup(). Instances are cached by the IDs, so repeated calls for the same airports share an instance. Instances that have not been fetched, or that are expired (more than 6 hours old), are removed from the cache. If the cached data is fresh, the Promise resolves immediately. Otherwise, the data is refreshed with fetch(). If a fetch is already in progress, the Promise for that fetch is returned.

The route is a single point if only one ID is provided. The function asserts that one or two IDs are provided.

Parameters

• id, id1, id2
  An airport identifier string. Two IDs specify the departure and destination airports.

Return value

A Promise that resolves with a ForecastWeather instance. The Promise rejects with an Error whose message is:

• 'Invalid airport' if an airport ID is not found.
• 'Offline' if the app is offline.
• 'failure' if the data could not be fetched or was incomplete. The reason is available in the instance's error property.

Constructor

Syntax

new ForecastWeather(route)

Constructs a new ForecastWeather instance for a route. The instance contains no forecast data until fetch() is called. The constructor computes the route distance and the waypoints on the route. Waypoints are the route points plus evenly spaced intermediate points along each great circle segment, no more than about 100 nm apart (at most 20 per segment).

Parameters

• route
  An array of objects with decimal degree latitude and longitude properties. It may have one point.

Instance methods

fetch()

fetch()

Fetch the forecast data for the instance's waypoints from the server. If the data is already valid and fresh, nothing is fetched. If a fetch is already in progress, the Promise for that fetch is returned. If the forecast data for any waypoint is missing, the fetch fails.

Return value

A Promise that resolves with the ForecastWeather instance when the data is fetched, or if the data is fresh. The Promise rejects with an Error with the message 'Offline' if the app is offline, 'Invalid input' if the instance has no waypoints, or 'failure' if the fetch failed, in which case the reason is saved in the error property. While a fetch is in progress, timestamp is 0, so the data is not valid.

getAltimeterAt()

getAltimeterAt()
getAltimeterAt(offset)
getAltimeterAt(offset, date)

Return the forecast altimeter setting at a point along the route. The setting is computed from the forecast surface pressure and waypoint elevation, and is rounded to two decimal places.

Parameters

• offset (optional)
  The distance from the departure in nm, or from the destination if negative. If omitted, 0 (the departure) is used.
• date (optional)
  A time in milliseconds since January 1, 1970 to select the forecast hour. If omitted, the current time is used.

Return value

The altimeter setting in inches of Mercury. The standard setting (29.92) is returned if the data is not valid, if the value is unusable, or if the route is a single point and offset is not 0.

getAverageAltimeter()

getAverageAltimeter()
getAverageAltimeter(offset)
getAverageAltimeter(offset, distance)
getAverageAltimeter(offset, distance, date)

Return the average forecast altimeter setting over a portion of the route.

Parameters

• offset (optional)
  The distance from the departure in nm of the start of the portion. If omitted, 0 is used.
• distance (optional)
  The length of the portion in nm. If omitted, the whole route distance is used.
• date (optional)
  A time in milliseconds since January 1, 1970 to select the forecast hour. If omitted, the current time is used.

Return value

The average altimeter setting in inches of Mercury, rounded to two decimal places. The standard setting (29.92) is returned if the data is not valid or the value is unusable.

getAverageFreezingLevel()

getAverageFreezingLevel()
getAverageFreezingLevel(offset)
getAverageFreezingLevel(offset, distance)
getAverageFreezingLevel(offset, distance, date)

Return the average forecast freezing level over a portion of the route.

Parameters

• offset (optional)
  The distance from the departure in nm of the start of the portion. If omitted, 0 is used.
• distance (optional)
  The length of the portion in nm. If omitted, the whole route distance is used.
• date (optional)
  A time in milliseconds since January 1, 1970 to select the forecast hour. If omitted, the current time is used.

Return value

The average freezing level in feet MSL, rounded to the nearest 1,000 feet, or null if the data is not valid or the value is unusable.

getAverageHeadwind()

getAverageHeadwind(altitude)
getAverageHeadwind(altitude, offset)
getAverageHeadwind(altitude, offset, distance)
getAverageHeadwind(altitude, offset, distance, date)

Return the average forecast headwind component over a portion of the route. This is the same as calling getEffectiveHeadwind() with a tas of 0, so the wind is not corrected for the crab angle.

Parameters

• altitude
  The pressure altitude in feet.
• offset (optional)
  The distance from the departure in nm of the start of the portion. If omitted, 0 is used.
• distance (optional)
  The length of the portion in nm. If omitted, the whole route distance is used.
• date (optional)
  A time in milliseconds since January 1, 1970 to select the forecast hour. If omitted, the current time is used.

Return value

The average headwind in knots, rounded to the nearest knot. A tailwind is negative. 0 is returned if the data is not valid, the route is a single point, or the value is unusable.

getAverageTemperature()

getAverageTemperature(altitude)
getAverageTemperature(altitude, offset)
getAverageTemperature(altitude, offset, distance)
getAverageTemperature(altitude, offset, distance, date)

Return the average forecast temperature over a portion of the route.

Parameters

• altitude
  The pressure altitude in feet.
• offset (optional)
  The distance from the departure in nm of the start of the portion. If omitted, 0 is used.
• distance (optional)
  The length of the portion in nm. If omitted, the whole route distance is used.
• date (optional)
  A time in milliseconds since January 1, 1970 to select the forecast hour. If omitted, the current time is used.

Return value

The average temperature in degrees Celsius, rounded to the nearest degree, or null if the data is not valid, the route is a single point, or the value is unusable.

getEffectiveHeadwind()

getEffectiveHeadwind(tas, altitude)
getEffectiveHeadwind(tas, altitude, offset)
getEffectiveHeadwind(tas, altitude, offset, distance)
getEffectiveHeadwind(tas, altitude, offset, distance, date)

Return the average forecast effective headwind over a portion of the route. The route portion is divided into its waypoint segments. For the midpoint of each segment, the forecast wind is found, and the angle between the route bearing and the wind direction is used to compute the headwind. The segment values are then averaged, weighted by segment length.

If tas is a nonzero number or function, the effective headwind from effectiveHeadwind() is computed. This is the true airspeed minus the ground speed, which accounts for the crab angle needed to hold the route course. If tas is a function, the true airspeed can change along the route, for example in a climb. The time that a segment takes to fly (the segment length divided by tas) is added to date so that later segments use later forecast hours. If tas is 0 or falsy, the simple headwind() component is computed.

Parameters

• tas
  A true airspeed in knots, or a function tas(offset, segmentLength) that returns the true airspeed in knots at a route offset (the segment midpoint) for a segment of segmentLength nm. 0 computes the simple headwind component.
• altitude
  The pressure altitude in feet.
• offset (optional)
  The distance from the departure in nm of the start of the portion. If omitted, 0 is used.
• distance (optional)
  The length of the portion in nm. If omitted, the whole route distance is used.
• date (optional)
  A time in milliseconds since January 1, 1970 to select the forecast hour. If omitted, the current time is used.

Return value

The average effective headwind in knots, rounded to the nearest knot. A tailwind is negative. 0 is returned if the data is not valid, the route is a single point, or the value is unusable (for example, if the crosswind exceeds the true airspeed).

getFreezingLevelAt()

getFreezingLevelAt()
getFreezingLevelAt(offset)
getFreezingLevelAt(offset, date)

Return the forecast freezing level at a point along the route.

Parameters

• offset (optional)
  The distance from the departure in nm, or from the destination if negative. If omitted, 0 (the departure) is used.
• date (optional)
  A time in milliseconds since January 1, 1970 to select the forecast hour. If omitted, the current time is used.

Return value

The freezing level in feet MSL, rounded to the nearest 1,000 feet, or null if the data is not valid or the value is unusable.

getTemperatureAt()

getTemperatureAt(altitude)
getTemperatureAt(altitude, offset)
getTemperatureAt(altitude, offset, date)

Return the forecast temperature at an altitude at a point along the route.

Parameters

• altitude
  The pressure altitude in feet.
• offset (optional)
  The distance from the departure in nm, or from the destination if negative. If omitted, 0 (the departure) is used.
• date (optional)
  A time in milliseconds since January 1, 1970 to select the forecast hour. If omitted, the current time is used.

Return value

The temperature in degrees Celsius, rounded to the nearest degree, or null if the data is not valid or the value is unusable.

getWindAt()

getWindAt(altitude, offset)
getWindAt(altitude, offset, date)

Return the forecast wind at an altitude at a point along the route. The returned object also includes the great circle bearing of the route at that point, so the wind can be resolved into headwind and crosswind components.

Parameters

• altitude
  The pressure altitude in feet.
• offset
  The distance from the departure in nm, or from the destination if negative.
• date (optional)
  A time in milliseconds since January 1, 1970 to select the forecast hour. If omitted, the current time is used.

Return value

An object with the following properties, each rounded to the nearest whole number, or null if the data is not valid or the value is unusable:

• speed
  The wind speed in knots.
• direction
  The direction the wind is coming from in degrees from true north.
• bearing
  The great circle bearing of the route at that point in degrees from true north.

isExpired()

isExpired()

Return whether the forecast data is older than 6 hours.

Return value

true if the data has been fetched and is more than 6 hours old. Otherwise, a falsy value (including if the data has never been fetched).

isFresh()

isFresh()

Return whether the forecast data was fetched within the last hour.

Return value

true if the data was fetched within the last hour. Otherwise, a falsy value.

isValid()

isValid()

Return whether the instance has forecast data that has not expired (it is less than 6 hours old). The data is not valid while a fetch is in progress.

Return value

true if the data is valid. Otherwise, a falsy value.

Instance properties

age

A read-only property that is the age of the forecast data in minutes, rounded to the nearest minute, or NaN if the data has not been fetched.

distance

The total great circle distance of the route in nautical miles. It is 0 if the route is a single point.

error

The error from the most recent failed fetch(), or null if there is none or a new fetch has started.

timestamp

The time the data was fetched in milliseconds since January 1, 1970, or 0 if the data has not been fetched or a fetch is in progress.

waypoints

An array of objects for the forecast waypoints along the route, in order from the departure. Each object has the following properties:

• loc
  An object with decimal degree latitude and longitude properties.
• offset
  The distance of the waypoint from the departure in nm.
• forecast
  The parsed forecast data for the waypoint, or null if not fetched. It is an array, sorted by time, of objects with date (milliseconds since January 1, 1970), freezingLevel (feet), altimeter (inHg), and altitudes properties. The altitudes property is an array, sorted by altitude, of objects with altitude (pressure altitude in feet), direction (degrees), speed (knots), and temperature (degrees Celsius) properties.