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.

Name	Type	Default	Description
cloud_coverage	int	None	The current cloud coverage in %.
condition	string	Required	The current weather condition.
humidity	float	None	The current humidity in %.
native_apparent_temperature	float	None	The current apparent (feels-like) temperature in °C or °F.
native_dew_point	float	None	The dew point temperature in °C or °F.
native_precipitation_unit	string	None	The precipitation unit; mm or in.
native_pressure	float	None	The current air pressure in hPa, mbar, inHg or mmHg.
native_pressure_unit	string	None	The air pressure unit; hPa, mbar, inHg or mmHg. Required if native_pressure is set.
native_temperature	float	Required	The current temperature in °C or °F.
native_temperature_unit	string	Required	The temperature unit; °C or °F.
native_visibility	float	None	The current visibility in km or mi.
native_visibility_unit	string	None	The visibility unit; km or mi. Required if native_visibility is set.
native_wind_gust_speed	float	None	The current wind gust speed in m/s, km/h, mi/h, ft/s or kn.
native_wind_speed	float	None	The current wind speed in m/s, km/h, mi/h, ft/s or kn.
native_wind_speed_unit	string	None	The wind speed unit;m/s, km/h, mi/h, ft/s or kn. Required if native_wind_speed is set.
ozone	float	None	The current ozone level.
uv_index	float	None	The current UV index.
wind_bearing	float or string	None	The 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.

Recommended values for state and condition

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

Condition	Description
clear-night	Clear night
cloudy	Many clouds
exceptional	Exceptional
fog	Fog
hail	Hail
lightning	Lightning/ thunderstorms
lightning-rainy	Lightning/ thunderstorms and rain
partlycloudy	A few clouds
pouring	Pouring rain
rainy	Rain
snowy	Snow
snowy-rainy	Snow and Rain
sunny	Sunshine
windy	Wind
windy-variant	Wind 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.

Value	Description
FORECAST_DAILY	The device supports a daily forecast.
FORECAST_HOURLY	The device supports an hourly forecast.
FORECAST_TWICE_DAILY	The 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.

Name	Type	Default	Description
datetime	string	Required	UTC Date time in RFC 3339 format.
is_daytime	bool	None	This is mandatory in forecast data returned by async_forecast_twice_daily to indicate day or night.
cloud_coverage	int	None	The cloud coverage in %.
condition	string	None	The weather condition at this point.
humidity	float	None	The humidity in %.
native_apparent_temperature	float	None	The apparent (feels-like) temperature in °C or °F
native_dew_point	float	None	The dew point temperature in °C or °F
native_precipitation	float	None	The precipitation amount in mm or in.
native_pressure	float	None	The air pressure in hPa, mbar, inHg or mmHg.
native_temperature	float	Required	The higher temperature in °C or °F
native_templow	float	None	The lower daily Temperature in °C or °F
native_wind_gust_speed	int	None	The wind gust speed in m/s, km/h, mi/h, ft/s or kn.
native_wind_speed	int	None	The wind speed in m/s, km/h, mi/h, ft/s or kn.
precipitation_probability	int	None	The probability of precipitation in %.
uv_index	float	None	The UV index.
wind_bearing	float or string	None	The 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.