From 0cf007f4f4854f0518b25224728ba57fab86aba7 Mon Sep 17 00:00:00 2001 From: Erik Montnemery Date: Tue, 8 Aug 2023 19:45:28 +0200 Subject: [PATCH] Document weather.get_forecast service (#28483) * Document weather.get_forecast service * Update source/_integrations/weather.markdown * Correct example * Apply suggestions from code review Co-authored-by: G Johansson * Update weather.markdown * Update weather.markdown --------- Co-authored-by: G Johansson --- source/_integrations/weather.markdown | 82 ++++++++++++++++++++++++--- 1 file changed, 75 insertions(+), 7 deletions(-) diff --git a/source/_integrations/weather.markdown b/source/_integrations/weather.markdown index 63d42e8ac11..1612ea56e7a 100644 --- a/source/_integrations/weather.markdown +++ b/source/_integrations/weather.markdown @@ -15,7 +15,10 @@ The `weather` platforms gather meteorological information from web services and Home Assistant currently supports free web services some of which require registration. -## Condition mapping +## State and state attributes + +A weather entity's state is used to indicate the current overall conditions, e.g. 'cloudy' or 'sunny'. +### Condition mapping The `weather` platform only knows the below listed conditions. The reason for this is that for these conditions is an icon from [Material Design Icons](https://pictogrammers.com/library/mdi/) available and mapped in the frontend. @@ -35,21 +38,85 @@ The `weather` platform only knows the below listed conditions. The reason for th - 'windy-variant' - 'exceptional' -### Forecast Information +### State attributes -Periodic forecast information is stored in the `forecast` attribute on the entity. To access and use the information should be reserved for advanced users using [Templates](/docs/configuration/templating/). +Detailed weather conditions as well as the unit of measurements used for the conditions are indicated by state attributes. A weather entity may not support all the state attributes. +{% raw %} ```yaml -temperature: 14.2 -temperature_unit: °C +apparent_temperature: 12.0 +cloud_coverage: 0 +dew_point: 5.0 humidity: 76 +precipitation_unit: mm pressure: 1019 pressure_unit: hPa +temperature: 14.2 +temperature_unit: °C +uv_index: 2 +visibility: 10 +visibility_unit: km wind_bearing: 260 +wind_gust_speed: 51.56 wind_speed: 35.17 wind_speed_unit: km/h -visibility_unit: km -precipitation_unit: mm +``` +{% endraw %} + +## Service `weather.get_forecast` + +Weather integrations which support weather forecasts expose the forecast using services. The services provided by weather entities are described below, and you can also read more about [Service Calls](/docs/scripts/service-calls/). + +
+ +Some integrations may not support the `weather.get_forecast` service, but instead expose weather forecasts as a state attribute named `forecast`. This behavior is deprecated and will be removed in a future release of Home Assistant Core. + +
+ +This service populates [Response Data](/docs/scripts/service-calls#use-templates-to-handle-response-data) +with a weather forecast. + +| Service data attribute | Optional | Description | Example | +| ---------------------- | -------- | ----------- | --------| +| `type` | no | The type of forecast, must be one of `daily`, `twice_daily` or `hourly`. | daily + +{% raw %} +```yaml +service: weather.get_forecast +target: + entity_id: weather.home +data: + type: daily +response_variable: weather_forecast +``` +{% endraw %} + +The response data field `forecast` is a list of forecasted conditions at a given point in time: + +| Response data | Description | Example | +| ---------------------- | ----------- | -------- | +| `datetime` | The time of the forecasted conditions. | 2023-02-17T14:00:00+00:00 +| `is_daytime` | Only set for `twice_daily` forecasts. | False +| `apparent_temperature` | The apparent (feels-like) temperature in the unit indicated by the `temperature_unit` state attribute. | 10.2 +| `cloud_coverage` | The cloud coverage in %. | 15 +| `condition` | The weather condition. | Sunny +| `dew_point` | The dew point temperature in the unit indicated by the `temperature_unit` state attribute. | 6.0 +| `humidity` | The relative humidity in %. | 82 +| `precipitation_probability` | The probability of precipitation in %. | 0 +| `precipitation` | The precipitation amount in the unit indicated by the `precipitation_unit` state attribute. | 0 +| `pressure` | The air pressure in the unit indicated by the `pressure_unit` state attribute. | 1019 +| `temperature` | The temperature in the unit indicated by the `temperature_unit` state attribute. If templow is also provided, this is the higher temperature. | 14.2 +| `templow` | The lower temperature in the unit indicated by the `temperature_unit` state attribute. | 5.0 +| `uv_index` | The UV index. | 3 +| `wind_bearing` | The wind bearing in azimuth angle (degrees) or 1-3 letter cardinal direction. | 268 +| `wind_gust_speed` | The wind gust speed in the unit indicated by the `wind_speed_unit` state attribute. | 34.41 +| `wind_speed` | The wind speed in the unit indicated by the `wind_speed_unit` state attribute. | 24.41 + + +Example forecast: + +{% raw %} +```yaml forecast: - condition: cloudy precipitation_probability: 0 @@ -76,3 +143,4 @@ forecast: wind_speed: 20.27 precipitation: 0 ``` +{% endraw %}