Skip to main content

Weather entity

Derive entity platforms from homeassistant.components.weather.WeatherEntity

Properties

tip

Properties should always only return information from memory and not do I/O (like network requests). Implement update() or async_update() to fetch data.

NameTypeDefaultDescription
cloud_coverageintNoneThe current cloud coverage in %.
conditionstringRequiredThe current weather condition.
humidityfloatNoneThe current humidity in %.
native_apparent_temperaturefloatNoneThe current apparent (feels-like) temperature in °C or °F.
native_dew_pointfloatNoneThe dew point temperature in °C or °F.
native_precipitation_unitstringNoneThe precipitation unit; mm or in.
native_pressurefloatNoneThe current air pressure in hPa, mbar, inHg or mmHg.
native_pressure_unitstringNoneThe air pressure unit; hPa, mbar, inHg or mmHg. Required if native_pressure is set.
native_temperaturefloatRequiredThe current temperature in °C or °F.
native_temperature_unitstringRequiredThe temperature unit; °C or °F.
native_visibilityfloatNoneThe current visibility in km or mi.
native_visibility_unitstringNoneThe visibility unit; km or mi. Required if native_visibility is set.
native_wind_gust_speedfloatNoneThe current wind gust speed in m/s, km/h, mi/h, ft/s or kn.
native_wind_speedfloatNoneThe current wind speed in m/s, km/h, mi/h, ft/s or kn.
native_wind_speed_unitstringNoneThe wind speed unit;m/s, km/h, mi/h, ft/s or kn. Required if native_wind_speed is set.
ozonefloatNoneThe current ozone level.
uv_indexfloatNoneThe current UV index.
wind_bearingfloat or stringNoneThe current wind bearing in azimuth angle (degrees) or 1-3 letter cardinal direction.

Unit conversion

Properties have to follow the units mentioned on the respective unit of measurement in the table.

To the user, properties will be presented according to the unit system. This is achieved by automatically converting units when creating state objects.

For each weather entity, the user also has the option to override the presentation units, i.e., the units used in the state objects.

These weather conditions are included in our translation files and also show the corresponding icon.

ConditionDescription
clear-nightClear night
cloudyMany clouds
exceptionalExceptional
fogFog
hailHail
lightningLightning/ thunderstorms
lightning-rainyLightning/ thunderstorms and rain
partlycloudyA few clouds
pouringPouring rain
rainyRain
snowySnow
snowy-rainySnow and Rain
sunnySunshine
windyWind
windy-variantWind and clouds

This means that the weather platforms don't need to support languages.

Supported features

Supported features are defined by using values in the WeatherEntityFeature enum and are combined using the bitwise or (|) operator.

ValueDescription
FORECAST_DAILYThe device supports a daily forecast.
FORECAST_HOURLYThe device supports an hourly forecast.
FORECAST_TWICE_DAILYThe device supports a twice-daily forecast.

Weather forecasts

A weather platform can optionally provide weather forecasts. Support for weather forecasts is indicated by setting the correct supported feature. Weather forecasts are not part of the entity's state, they're instead made available by a separate API. Consumers, e.g. frontend, can subscribe to weather forecast updates.

Forecast data

Forecast data can be daily, hourly or twice_daily. An integration can provide any or all of them.

The integration should implement one or several of the async methods async_forecast_daily, async_forecast_hourly and async_forecast_twice_daily documented below to fetch the forecast data.

NameTypeDefaultDescription
datetimestringRequiredUTC Date time in RFC 3339 format.
is_daytimeboolNoneThis is mandatory in forecast data returned by async_forecast_twice_daily to indicate day or night.
cloud_coverageintNoneThe cloud coverage in %.
conditionstringNoneThe weather condition at this point.
humidityfloatNoneThe humidity in %.
native_apparent_temperaturefloatNoneThe apparent (feels-like) temperature in °C or °F
native_dew_pointfloatNoneThe dew point temperature in °C or °F
native_precipitationfloatNoneThe precipitation amount in mm or in.
native_pressurefloatNoneThe air pressure in hPa, mbar, inHg or mmHg.
native_temperaturefloatRequiredThe higher temperature in °C or °F
native_templowfloatNoneThe lower daily Temperature in °C or °F
native_wind_gust_speedintNoneThe wind gust speed in m/s, km/h, mi/h, ft/s or kn.
native_wind_speedintNoneThe wind speed in m/s, km/h, mi/h, ft/s or kn.
precipitation_probabilityintNoneThe probability of precipitation in %.
uv_indexfloatNoneThe UV index.
wind_bearingfloat or stringNoneThe wind bearing in azimuth angle (degrees) or 1-3 letter cardinal direction.

Forecast data needs to follow the same unit of measurement as defined for properties where applicable.

Methods to get weather forecast(s)

These method are called to fetch forecasts from the api.

class MyWeatherEntity(WeatherEntity):
"""Represent a Weather entity."""

async def async_forecast_daily(self) -> list[Forecast] | None:
"""Return the daily forecast in native units.

Only implement this method if `WeatherEntityFeature.FORECAST_DAILY` is set
"""

async def async_forecast_twice_daily(self) -> list[Forecast] | None:
"""Return the twice daily forecast in native units.

Only implement this method if `WeatherEntityFeature.FORECAST_TWICE_DAILY` is set
"""

async def async_forecast_hourly(self) -> list[Forecast] | None:
"""Return the hourly forecast in native units.

Only implement this method if `WeatherEntityFeature.FORECAST_HOURLY` is set
"""

Updating weather forecast(s)

It is strongly recommended that fetched weather forecasts are cached by the weather entity to avoid unnecessary API accesses.

When an updated weather forecast is available, the weather forecast cache should be invalidated and the method WeatherEntity.async_update_listeners should be awaited to trigger a push of the updated weather forecast to any active subscriber. If there are active listeners, WeatherEntity.async_update_listeners will call the corresponding async_forecast_xxx methods. If there are no active listeners, WeatherEntity.async_update_listeners will not call any ot the async_forecast_xxx methods.