jeans/home-assistant.io
jeans/home-assistant.io
1
0
Fork 0
mirror of https://github.com/home-assistant/home-assistant.io.git synced 2025-07-23 01:06:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add documentation for weather.get_forecasts (#30189)

Browse Source 
* Add documentation for `weather.get_forecasts`

This was missed as part of the 2023.12 release. Document
the new service and note the old is now deprecated.

* Tiny tweaks

* remove raw tags

* Apply suggestions from code review

* Update per review.

* Remove old deprecated service
* Put example to hourly and specify daily is the default
* Put example response in a details block.

* Update temlplate example to use get_forecasts.

* Update python script example for get_forecasts.

* Update source/_integrations/weather.markdown

Co-authored-by: Martin Hjelmare <marhje52@gmail.com>

* Update source/_integrations/weather.markdown

Co-authored-by: Martin Hjelmare <marhje52@gmail.com>

* Update examples for weather.get_forecasts

* Review update

Simplify template example for get_forecasts documentation.

---------

Co-authored-by: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com>
Co-authored-by: Martin Hjelmare <marhje52@gmail.com>
This commit is contained in:
Mike O'Driscoll 2023-12-12 02:49:28 -05:00 committed by GitHub
parent 7e04cdee2e
commit d5ad6ddc18
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 93 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
source/_integrations/python_script.markdown
View File

@ -132,8 +132,8 @@ Services can also respond with data. Retrieving this data in your Python script
```python
# get_forecast.py
service_data = {"type": "daily", "entity_id": "weather.YOUR_HOME"}
current_forecast = hass.services.call("weather", "get_forecast", service_data, blocking=True, return_response=True)
service_data = {"type": "daily", "entity_id": ["weather.YOUR_HOME", "weather.YOUR_SCHOOL"]}
current_forecast = hass.services.call("weather", "get_forecasts", service_data, blocking=True, return_response=True)
```
## Documenting your Python scripts

4
source/_integrations/template.markdown
View File

@ -779,7 +779,7 @@ template:
- platform: time_pattern
hours: /1
action:
- service: weather.get_forecast
- service: weather.get_forecasts
data:
type: hourly
target:
@ -790,7 +790,7 @@ template:
unique_id: weather_forecast_hourly
state: "{{ now().isoformat() }}"
attributes:
forecast: "{{ hourly.forecast }}"
forecast: "{{ hourly['weather.home'].forecast }}"
```
{% endraw %}

136
source/_integrations/weather.markdown
View File

@ -49,7 +49,6 @@ The `weather` {% term entity %} can provide the conditions listed below as its s
Detailed weather conditions as well as the unit of measurements used for the conditions are indicated by state attributes. A weather {% term entity %} may not support all the state attributes.
{% raw %}
```yaml
apparent_temperature: 12.0
cloud_coverage: 0
@ -68,37 +67,29 @@ wind_gust_speed: 51.56
wind_speed: 35.17
wind_speed_unit: km/h
```
{% endraw %}
## Service `weather.get_forecast`
## Service `weather.get_forecasts`
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/).
<div class='note'>
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.
</div>
This service populates [Response Data](/docs/scripts/service-calls#use-templates-to-handle-response-data)
with a weather forecast.
This service populates [response data](/docs/scripts/service-calls#use-templates-to-handle-response-data)
with a mapping of weather services and their associated forecasts.
| Service data attribute | Optional | Description | Example |
| ---------------------- | -------- | ----------- | --------|
| `type` | no | The type of forecast, must be one of `daily`, `twice_daily` or `hourly`. | daily
| `type` | no | The type of forecast, must be one of `daily`, `twice_daily`, or `hourly`. The default is `daily`. | daily
{% raw %}
```yaml
service: weather.get_forecast
service: weather.get_forecasts
target:
entity_id: weather.home
entity_id:
- weather.tomorrow_io_home_nowcast
- weather.toronto_forecast
data:
type: daily
type: hourly
response_variable: weather_forecast
```
{% endraw %}
The response data field `forecast` is a list of forecasted conditions at a given point in time:
The response data field is a mapping of called target entities, each containing the `forecast` field.
`forecast` is a list of forecasted conditions at a given point in time:
| Response data | Description | Example |
| ---------------------- | ----------- | -------- |
@ -112,7 +103,7 @@ The response data field `forecast` is a list of forecasted conditions at a given
| `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
| `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
@ -120,34 +111,85 @@ The response data field `forecast` is a list of forecasted conditions at a given
| `wind_speed` | The wind speed in the unit indicated by the `wind_speed_unit` state attribute. | 24.41
Example forecast:
## Examples
{% details "Example template sensor using get_forecasts" %}
Example template sensor that contains the hourly forecast
{% raw %}
```yaml
forecast:
- condition: cloudy
precipitation_probability: 0
datetime: '2023-02-17T14:00:00+00:00'
wind_bearing: 268
temperature: 14.2
pressure: 1019
wind_speed: 24.41
precipitation: 0
- condition: cloudy
precipitation_probability: 0
datetime: '2023-02-17T15:00:00+00:00'
wind_bearing: 268
temperature: 13.8
pressure: 1019
wind_speed: 22.61
precipitation: 0
- condition: cloudy
precipitation_probability: 0
datetime: '2023-02-17T16:00:00+00:00'
wind_bearing: 265
temperature: 13.2
pressure: 1020
wind_speed: 20.27
precipitation: 0
template:
- trigger:
- platform: time_pattern
hours: /1
action:
- service: weather.get_forecasts
data:
type: hourly
target:
entity_id: weather.home
response_variable: hourly
sensor:
- name: Temperature forecast next hour
unique_id: temperature_forecast_next_hour
state: "{{ hourly['weather.home'].forecast[0].temperature }}"
unit_of_measurement: °C
```
{% endraw %}
{% enddetails %}
{% details "Example service response" %}
```yaml
weather.tomorrow_io_home_nowcast:
forecast:
- datetime: "2023-12-07T13:00:00+00:00"
condition: cloudy
precipitation_probability: 0
wind_bearing: 241.19
temperature: 0.1
dew_point: -1.9
wind_speed: 16.88
precipitation: 0
humidity: 86
- datetime: "2023-12-07T14:00:00+00:00"
condition: cloudy
precipitation_probability: 0
wind_bearing: 232.41
temperature: 0.8
dew_point: -2.8
wind_speed: 17.82
precipitation: 0
humidity: 77
- datetime: "2023-12-07T15:00:00+00:00"
condition: cloudy
precipitation_probability: 0
wind_bearing: 236.09
temperature: 1.1
dew_point: -2.6
wind_speed: 17.89
precipitation: 0
humidity: 77
weather.toronto_forecast:
forecast:
- datetime: "2023-12-07T14:00:00+00:00"
condition: snowy
precipitation_probability: 40
temperature: 0
- datetime: "2023-12-07T15:00:00+00:00"
condition: snowy
precipitation_probability: 40
temperature: 0
- datetime: "2023-12-07T16:00:00+00:00"
condition: snowy
precipitation_probability: 40
temperature: 0
```
{% enddetails %}