Weather entity

A weather entity reports the current weather at a location: the condition, the temperature, and readings like humidity and wind. It can also serve forecasts. Inherit from WeatherEntity, imported from homeassistant.components.weather. If you use a coordinator, inherit from CoordinatorWeatherEntity or SingleCoordinatorWeatherEntity instead (see using coordinators).

To see how the frontend shows a weather entity, see the weather more-info view.

Set every value in its native unit, and tell Home Assistant which unit that is. The base class converts the values to the unit system of the user, or to the units the user picked in the entity settings.

When a native_*_unit is None, the base class assumes the value is already in the default unit of the user's unit system, and converts from that unit when the user picked another one for the entity. So set the unit for every kind of value you report.

The generic properties every entity has, like name or available, are on the entity class. In practice, every weather entity sets at least condition, native_temperature, and native_temperature_unit.

Each forecast type is a flag in WeatherEntityFeature. Combine them with |, and implement the method that goes with each one.

See supported features for how flags work in general.

Use one of these values for condition. They are translated and get a matching icon in the frontend, so your integration does not need to translate them.

They are available as ATTR_CONDITION_* constants in homeassistant.components.weather, like ATTR_CONDITION_SUNNY.

Forecasts are not part of the state. Consumers like the frontend subscribe to them over a separate API, and the weather.get_forecasts action returns them. The base class converts forecast values to the user's units, just like the current values.

Each forecast method returns a list of Forecast dictionaries, in native units:

The units are the same native_*_unit properties as for the current values.

Cache the forecasts you fetch, so you do not call the API every time someone asks. When you have new forecast data, await self.async_update_listeners(None) to push it to every subscriber, or pass a list of forecast types, like ["daily"], to push only those. When nobody is subscribed, it does not call your forecast methods at all.

CoordinatorWeatherEntity connects a weather entity to coordinators: one for the current observation, and optionally one per forecast type. Pass them to __init__ as daily_coordinator, hourly_coordinator, and twice_daily_coordinator. Instead of the async forecast methods, you implement the callbacks _async_forecast_daily, _async_forecast_hourly, and _async_forecast_twice_daily, which read from coordinator data. Listeners are updated when a coordinator updates.

The forecast coordinators must be a TimestampDataUpdateCoordinator. The entity only listens to a forecast coordinator while someone is subscribed to that forecast type. When a forecast is requested and the data of its coordinator is older than its update_interval, the entity refreshes the coordinator first. Pass daily_forecast_valid, hourly_forecast_valid, or twice_daily_forecast_valid to __init__ to set how old a forecast may get before the entity returns None instead. It defaults to the update_interval of the coordinator. A coordinator without an update_interval, like one that only receives pushed data, skips both checks: the entity never refreshes it and never rejects its forecast as too old.

SingleCoordinatorWeatherEntity is the shortcut for one coordinator that holds both the observation and the forecasts.

async def async_forecast_daily(self) -> list[Forecast] | None:
async def async_forecast_hourly(self) -> list[Forecast] | None:
async def async_forecast_twice_daily(self) -> list[Forecast] | None:

Implement only the ones you declared in the supported features. There are no sync variants.

The state is condition. The current values become state attributes, in the units of the user. Do not set state yourself.

A weather entity with a daily forecast:

from homeassistant.components.weather import (
    Forecast,
    WeatherEntity,
    WeatherEntityFeature,
)
from homeassistant.const import UnitOfSpeed, UnitOfTemperature


class ExampleWeather(WeatherEntity):
    """Weather from an example service."""

    _attr_has_entity_name = True
    _attr_name = None
    _attr_native_temperature_unit = UnitOfTemperature.CELSIUS
    _attr_native_wind_speed_unit = UnitOfSpeed.METERS_PER_SECOND
    _attr_supported_features = WeatherEntityFeature.FORECAST_DAILY

    def __init__(self, client: ExampleClient, location_id: str) -> None:
        """Initialize the weather entity."""
        self._client = client
        self._attr_unique_id = location_id

    async def async_update(self) -> None:
        """Fetch the current weather."""
        current = await self._client.get_current()
        self._attr_condition = current.condition
        self._attr_native_temperature = current.temperature
        self._attr_native_wind_speed = current.wind_speed

    async def async_forecast_daily(self) -> list[Forecast] | None:
        """Return the daily forecast."""
        days = await self._client.get_daily_forecast()
        return [
            Forecast(
                datetime=day.date.isoformat(),
                condition=day.condition,
                native_temperature=day.high,
                native_templow=day.low,
            )
            for day in days
        ]