Weather Fundamentals

Core Concepts

Location (Where is the Weather?):

Concept: Weather data is always tied to a specific geographic point or area. It's not just "the temperature," but "the temperature in London" or "the temperature at these exact coordinates."

This is the primary input for almost any weather API request and you'll always need to specify a location (e.g., latitude/longitude, city name, postal code) and the data received will be relevant only to that specified location. Point vs gridded data.

Time (When is the Weather?):

Concept: Weather is dynamic; it changes constantly. Every piece of weather data is associated with a specific moment in time or a time range.

You need to distinguish between:

Current Conditions: What's happening right now.

Forecast: What's expected to happen in the future (e.g., next hour, next 24 hours, next 7 days).

Historical Data: What did happen in the past.

Understanding the timestamp or period associated with each data point is crucial for displaying accurate and relevant information.

Weather Variables (The "What" We Measure):

Concept: These are the specific atmospheric conditions that are being measured or predicted. Think of them as the "types of data" you're getting.

This includes things like:

Temperature: How hot or cold it is.

Wind: How fast the air is moving and in what direction.

Precipitation: Whether it's raining, snowing, etc., and how much.

Humidity: How much moisture is in the air.

Cloud Cover: How much of the sky is covered by clouds.

The API will provide specific fields for each of these in the responses, and you'll need to map these fields to their meaning.

Units of Measurement:

Concept: Every numerical weather variable comes with a unit that defines its scale. A number like 25 means nothing without knowing if it's 25 degrees Celsius, 25 miles per hour, or 25 millimeters.

You'll need to be aware of the units used in the API response (e.g., Celsius vs. Fahrenheit, km/h vs. mph, hPa vs. inHg). This is critical for correct display to end-users and for any calculations or comparisons. Our APIs generally have a single default unit but we allow specifying preferred units in a few cases.

Observation vs Nowcast vs Forecast vs Hindcast (The "Source" of the Data):

Concept: Is the data based on actual measurements taken by sensors (observation), or is it a prediction generated by complex computer models (forecast)?

This distinction is key for setting user expectations. Observations are "facts" about the past/present. Forecasts are "predictions" about the future and come with inherent uncertainty. Hindcasts are forecasts run on historical data to understand what the forecast would have been at any point in time. Nowcasts are short-term forecasts run with real-time observations being fed in to increase accuracy. You should understand that forecast accuracy decreases the further into the future you look, and that different forecast models might produce slightly different results.

Weather Models

Concept: A weather model is a complex computer program that uses mathematical equations to simulate the Earth's atmosphere and predict future weather conditions. It takes current weather observations as input and uses them to forecast how the atmosphere will evolve over time.

Weather models primarily fall into two main categories: global models, which cover the entire Earth with coarser resolution for long-range forecasts, and regional (or mesoscale) models, which focus on smaller areas with higher resolution to predict localized weather phenomena. Additionally, both types can be either deterministic, providing a single forecast, or ensemble models, which run multiple simulations to assess forecast uncertainty. All the models currently offered are deterministic.

Prominent weather models include global models like the European Centre for Medium-Range Weather Forecasts (ECMWF) and the Global Forecast System (GFS), and regional models such as 4km and 8km WRF provided by MetService or X model provided by MetraWeather for Australia.

Regional models typically higher resolution and accuracy when compared to equivalent global models.

The individual API pages specify which weather models are available, but the following is a list of models available on the platform:

• ECMWF
• GFS
• NZ 4km WRF
• NZ 8km WRF

Understanding Meteorological Data

Temperature (and "Feels Like" Temperature):

Concept: This is more nuanced than just a single number. Developers will encounter various temperature types:

Air Temperature: The standard temperature of the air.

Dew Point Temperature: The temperature at which air becomes saturated with water vapor and dew begins to form. Crucial for understanding humidity and the likelihood of fog or precipitation.

"Feels Like" / Apparent Temperature: A calculated value that combines air temperature with other factors like humidity (for heat index) and wind (for wind chill) to represent how the temperature feels to a human.

Developer Relevance: Understanding the difference between these values is vital for displaying relevant information to end-users (e.g., showing "feels like" for comfort, or dew point for agricultural apps) and for selecting the correct data fields from an API response. Pay attention to units (Celsius, Fahrenheit, Kelvin).

Precipitation (Type, Intensity, Probability):

Concept: Precipitation isn't just "rain." Data often includes:

Type: Rain, snow, sleet, hail, drizzle, freezing rain.

Intensity: Light, moderate, heavy (often measured in mm/hr or inches/hr).

Accumulation: Total amount over a period (e.g., 24-hour rainfall).

Probability of Precipitation (PoP): The likelihood (as a percentage) that any measurable precipitation will occur at a given location within a specific forecast period. It's not about how much, but if it will happen at all.

Developer Relevance: Developers need to parse different precipitation types for icons/display, understand intensity for alerts, and correctly interpret PoP (e.g., a 30% PoP doesn't mean 30% of the area gets rain, but a 30% chance of any rain at that point).

Wind (Speed, Direction, Gusts):

Concept: Wind is described by both its speed and its direction.

Speed: Typically measured in km/h, mph, knots, or m/s.

Direction: Often given as a compass direction (N, NE, SW) or in degrees (0-360°, where 0/360 is North). This is usually the direction from which the wind is blowing.

Gusts: The maximum instantaneous wind speed, which can be significantly higher than the average wind speed and is important for safety.

Developer Relevance: Crucial for displaying wind arrows, warnings for high winds, and for applications related to aviation, marine, or outdoor activities. Be mindful of the unit of speed and the convention for direction.

Atmospheric Pressure:

Concept: The force exerted by the weight of the air above a given point.

High Pressure: Generally associated with stable, clear, fair weather.

Low Pressure: Generally associated with unstable, cloudy, stormy weather.

Units: Commonly measured in hectopascals (hPa), millibars (mb), or inches of mercury (inHg).

Developer Relevance: While not always displayed directly to end-users, understanding pressure trends (rising, falling) can provide context for weather changes. It's a fundamental input for many weather models and can be used in more advanced visualizations or analyses.

Humidity (Relative Humidity & Dew Point):

Concept: Humidity refers to the amount of water vapor in the air.

Relative Humidity (RH): The most common measure, expressed as a percentage, indicating how much moisture the air holds relative to how much it could hold at that temperature. High RH (near 100%) means the air is nearly saturated.

Dew Point: (Reiterated from temperature, but crucial here) A more absolute measure of moisture. A high dew point indicates a lot of moisture in the air, regardless of temperature.

Developer Relevance: RH affects comfort (humid vs. dry), evaporation rates, and fire risk. Dew point is a better indicator of actual moisture content and is critical for predicting fog, dew, and understanding how "muggy" it feels. Developers need to know which metric to use for different use cases.

Meterological Units

All numerical values for temperature, wind speed, and wind direction in the Nowcast API are provided in SI units as the default and only option, consistent with our platform's default data representation.

• Temperature: Celsius (^\\circ C)
• Wind Speed: Kilometers per hour (km/h)
• Wind Direction: Degrees (0-359, where 0 is North)

If it'd be valuable to have the API provide nowcast responses with other units let us know HERE to help us prioritise it.

CF JSON compliant responses