mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-15 21:36:52 +00:00
Add documentation for weather.get_forecasts
(#30189)
* 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:
parent
7e04cdee2e
commit
d5ad6ddc18
@ -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
|
||||
|
@ -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 %}
|
||||
|
@ -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 %}
|
Loading…
x
Reference in New Issue
Block a user