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>

source/_integrations/python_script.markdown

@@ -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"}
+service_data = {"type": "daily", "entity_id": ["weather.YOUR_HOME", "weather.YOUR_SCHOOL"]}
-current_forecast = hass.services.call("weather", "get_forecast", service_data, blocking=True, return_response=True)
+current_forecast = hass.services.call("weather", "get_forecasts", service_data, blocking=True, return_response=True)
 ```
 
 ## Documenting your Python scripts

source/_integrations/template.markdown

@@ -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 %}

source/_integrations/weather.markdown

@@ -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/).
+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.
-<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.
 
 | 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:
+template:
-  - condition: cloudy
+  - trigger:
-    precipitation_probability: 0
+      - platform: time_pattern
-    datetime: '2023-02-17T14:00:00+00:00'
+        hours: /1
-    wind_bearing: 268
+    action:
-    temperature: 14.2
+      - service: weather.get_forecasts
-    pressure: 1019
+        data:
-    wind_speed: 24.41
+          type: hourly
-    precipitation: 0
+        target:
-  - condition: cloudy
+          entity_id: weather.home
-    precipitation_probability: 0
+        response_variable: hourly
-    datetime: '2023-02-17T15:00:00+00:00'
+    sensor:
-    wind_bearing: 268
+      - name: Temperature forecast next hour
-    temperature: 13.8
+        unique_id: temperature_forecast_next_hour
-    pressure: 1019
+        state: "{{ hourly['weather.home'].forecast[0].temperature }}"
-    wind_speed: 22.61
+        unit_of_measurement: °C
-    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
 ```
+
 {% 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 %}