Add premium forecast endpoints to SDK

docs/forecast.md

@@ -1,16 +1,18 @@
 # Forecast
-Get irradiance, weather and power forecasts from the present time up to 14 days ahead for 
-the requested location, derived from satellite (clouds and irradiance over non-polar continental areas, 
+Get irradiance, weather and power forecasts from the present time up to 14 days ahead for
+requested locations or resources, including premium PV and wind power forecasts, derived from satellite (clouds and irradiance over non-polar continental areas,
 nowcasted for approx. four hours ahead) and numerical weather models (other data and longer horizons).
 More information in the [API docs](https://docs.solcast.com.au/#49090b36-66db-4d0f-89d5-87d19f00bec1).
 
-The module `forecast` has 3 available methods:
+The module `forecast` has 5 available methods:
 
 | Endpoint                | API Docs                                                                                  |
 |-------------------------|-------------------------------------------------------------------------------------------|
 | `radiation_and_weather` | [details](https://docs.solcast.com.au/?#b78a2ee4-c8e5-4ae6-9fb3-c8bbefe91efc){.md-button} |
 | `rooftop_pv_power`      | [details](https://docs.solcast.com.au/?#25ff8ad7-e2a8-44be-9d2e-62e0f73cefd6){.md-button} |
 | `advanced_pv_power`     | [details](https://docs.solcast.com.au/?#0c9d3ccf-e2a4-4583-86a3-f89c8d658fde){.md-button} |
+| `premium_pv_power`      | [details](https://docs.solcast.com.au/docs/section/premium#getDataForecastPremiumPvPower){.md-button} |
+| `premium_wind_power`    | [details](https://docs.solcast.com.au/docs/section/premium#getDataForecastPremiumWindPower){.md-button} |
 
 ### Example
 

solcast/__init__.py

@@ -15,7 +15,7 @@
     "forecast",
     "historic",
     "live",
+    "pv_power_sites",
     "tmy",
     "unmetered_locations",
-    "pv_power_sites",
 ]

solcast/aggregations.py

@@ -37,7 +37,7 @@ def forecast(
     collection_id: str, aggregation_id: Optional[str], **kwargs
 ) -> PandafiableResponse:
     """
-    Get forecast aggregation data for up to 7 days of data at a time for a requested collection or aggregation.
+    Get forecast aggregation data for up to 14 days of data at a time for a requested collection or aggregation.
 
     Args:
         collection_id: a unique identifier for your collection.

solcast/forecast.py

@@ -4,6 +4,8 @@
 from .urls import (
     base_url,
     forecast_advanced_pv_power,
+    forecast_premium_pv_power,
+    forecast_premium_wind_power,
     forecast_radiation_and_weather,
     forecast_rooftop_pv_power,
     forecast_soiling_hsu,
@@ -15,23 +17,25 @@ def radiation_and_weather(
     latitude: float, longitude: float, output_parameters: List[str], **kwargs
 ) -> PandafiableResponse:
     """
-    Get irradiance and weather forecasts from the present time up to 14 days ahead
-    for the requested location, derived from satellite (clouds and irradiance
-    over non-polar continental areas, nowcasted for approx. four hours ahead)
-    and numerical weather models (other data and longer horizons).
+    Get irradiance and weather forecasts for the requested location from the present up
+    to 14 days ahead, derived from satellite (clouds and irradiance over non-polar
+    continental areas, nowcast for approx. four hours ahead) and numerical weather
+    models (other data and longer horizons).
 
     Args:
-        latitude: in decimal degrees, between -90 and 90, north is positive
-        longitude: in decimal degrees, between -180 and 180, east is positive
-        output_parameters: list of strings with the parameters to return
+        latitude: The latitude of the location you request data for. Must be a decimal
+            number between -90 and 90.
+        longitude: The longitude of the location you request data for. Must be a decimal
+            number between -180 and 180.
+        output_parameters: The output parameters to include in the response.
         **kwargs: additional keyword arguments to be passed through as URL parameters to the Solcast API
 
     See https://docs.solcast.com.au/ for full list of parameters.
     """
     client = Client(
         base_url=base_url,
         endpoint=forecast_radiation_and_weather,
-        response_type=PandafiableResponse,  # type: ignore[arg-type]
+        response_type=PandafiableResponse,
     )
 
     return client.get(
@@ -49,23 +53,28 @@ def rooftop_pv_power(
     latitude: float, longitude: float, output_parameters: List[str], **kwargs
 ) -> PandafiableResponse:
     """
-    Get basic rooftop PV power forecasts from the present time up to 14 days ahead
-    for the requested location, derived from satellite (clouds and irradiance
-    over non-polar continental areas, nowcasted for approx. four hours ahead)
-    and numerical weather models (other data and longer horizons).
+    Get basic rooftop PV power forecasts from the present time up to 14 days ahead for
+    the requested location, derived from satellite (clouds and irradiance over non-polar
+    continental areas, nowcasted for approx. four hours ahead) and numerical weather
+    models (other data and longer horizons).
+
+    The basic rooftop power simulation is only suitable for residential and smaller C&I
+    rooftop sites, not for grid-scale sites.
 
     Args:
-        latitude: in decimal degrees, between -90 and 90, north is positive
-        longitude: in decimal degrees, between -180 and 180, east is positive
-        output_parameters: list of strings with the parameters to return
+        latitude: The latitude of the location you request data for. Must be a decimal
+            number between -90 and 90.
+        longitude: The longitude of the location you request data for. Must be a decimal
+            number between -180 and 180.
+        output_parameters: The output parameters to include in the response.
         **kwargs: additional keyword arguments to be passed through as URL parameters to the Solcast API
 
     See https://docs.solcast.com.au/ for full list of parameters.
     """
     client = Client(
         base_url=base_url,
         endpoint=forecast_rooftop_pv_power,
-        response_type=PandafiableResponse,  # type: ignore[arg-type]
+        response_type=PandafiableResponse,
     )
 
     return client.get(
@@ -81,21 +90,21 @@ def rooftop_pv_power(
 
 def advanced_pv_power(resource_id: int, **kwargs) -> PandafiableResponse:
     """
-    Get high spec PV power forecasts from the present time up to 14 days ahead
-    for the requested site, derived from satellite (clouds and irradiance over
-    non-polar continental areas, nowcasted for approx. four hours ahead) and
-    numerical weather models (other data and longer horizons).
+    Get high-spec PV power forecasts for the requested site from the present up to 14
+    days ahead, derived from satellite (clouds and irradiance over non-polar continental
+    areas, nowcasted for approx. four hours ahead) and numerical weather models (other
+    data and longer horizons).
 
     Args:
-        resource_id: a Solcast resource id
+        resource_id: The resource id of the resource.
         **kwargs: additional keyword arguments to be passed through as URL parameters to the Solcast API
 
     See https://docs.solcast.com.au/ for full list of parameters.
     """
     client = Client(
         base_url=base_url,
         endpoint=forecast_advanced_pv_power,
-        response_type=PandafiableResponse,  # type: ignore[arg-type]
+        response_type=PandafiableResponse,
     )
 
     return client.get({"resource_id": resource_id, "format": "json", **kwargs})
@@ -106,28 +115,29 @@ def soiling_kimber(
     longitude: float,
     **kwargs,
 ) -> PandafiableResponse:
-    """Get hourly soiling loss forecast using the Kimber model.
-
-    Returns a time series of forecast cumulative soiling / cleanliness state for the
-    requested location based on Pvlib's Kimber model.
+    """
+    Get soiling loss forecasts using the Kimber model for the requested location from
+    the present up to 14 days ahead.
 
     Args:
-        latitude: Decimal degrees, between -90 and 90 (north positive).
-        longitude: Decimal degrees, between -180 and 180 (east positive).
-        **kwargs: Additional query parameters accepted by the endpoint (e.g. depo_veloc_pm10, initial_soiling).
+        latitude: The latitude of the location (EPSG:4326). Must be between -90 and 90.
+        longitude: The longitude of the location (EPSG:4326). Must be between -180 and
+            180.
+        **kwargs: additional keyword arguments to be passed through as URL parameters to the Solcast API
 
     Returns:
         PandafiableResponse: Response object; call `.to_pandas()` for a DataFrame.
 
-    See https://docs.solcast.com.au/ for full parameter details.
+    See https://docs.solcast.com.au/ for full list of parameters.
     """
     url = kwargs.pop("base_url", base_url)
 
     client = Client(
         base_url=url,
         endpoint=forecast_soiling_kimber,
-        response_type=PandafiableResponse,  # type: ignore[arg-type]
+        response_type=PandafiableResponse,
     )
+
     return client.get(
         {
             "latitude": latitude,
@@ -143,27 +153,30 @@ def soiling_hsu(
     longitude: float,
     **kwargs,
 ) -> PandafiableResponse:
-    """Get hourly soiling loss forecast using the HSU model.
-
-     Returns a time series of forecast cumulative soiling / cleanliness state for the
-     requested location based on Solcast's HSU model.
+    """
+    Get soiling loss forecasts using the HSU model for the requested location from the
+    present up to 14 days ahead.
 
-     Args:
-         latitude: Decimal degrees, between -90 and 90 (north positive).
-         longitude: Decimal degrees, between -180 and 180 (east positive).
-         **kwargs: Additional query parameters accepted by the endpoint (e.g. depo_veloc_pm10, initial_soiling).
+    Args:
+        latitude: The latitude of the location you request data for. Must be a decimal
+            number between -90 and 90.
+        longitude: The longitude of the location you request data for. Must be a decimal
+            number between -180 and 180.
+        **kwargs: additional keyword arguments to be passed through as URL parameters to the Solcast API
 
-     Returns:
-         PandafiableResponse: Response object; call `.to_pandas()` for a DataFrame.
+    Returns:
+        PandafiableResponse: Response object; call `.to_pandas()` for a DataFrame.
 
-    See https://docs.solcast.com.au/ for full parameter details.
+    See https://docs.solcast.com.au/ for full list of parameters.
     """
     url = kwargs.pop("base_url", base_url)
+
     client = Client(
         base_url=url,
         endpoint=forecast_soiling_hsu,
-        response_type=PandafiableResponse,  # type: ignore[arg-type]
+        response_type=PandafiableResponse,
     )
+
     return client.get(
         {
             "latitude": latitude,
@@ -172,3 +185,53 @@ def soiling_hsu(
             **kwargs,
         }
     )
+
+
+def premium_pv_power(resource_id: str, **kwargs) -> PandafiableResponse:
+    """
+    Get Forecast Premium PV
+
+    Args:
+        resource_id: The resource id of the resource.
+        **kwargs: additional keyword arguments to be passed through as URL parameters to the Solcast API
+
+    See https://docs.solcast.com.au/ for full list of parameters.
+    """
+    client = Client(
+        base_url=base_url,
+        endpoint=forecast_premium_pv_power,
+        response_type=PandafiableResponse,
+    )
+
+    return client.get(
+        {
+            "resource_id": resource_id,
+            "format": "json",
+            **kwargs,
+        }
+    )
+
+
+def premium_wind_power(resource_id: str, **kwargs) -> PandafiableResponse:
+    """
+    Get Forecast Premium Wind
+
+    Args:
+        resource_id: The resource id of the resource.
+        **kwargs: additional keyword arguments to be passed through as URL parameters to the Solcast API
+
+    See https://docs.solcast.com.au/ for full list of parameters.
+    """
+    client = Client(
+        base_url=base_url,
+        endpoint=forecast_premium_wind_power,
+        response_type=PandafiableResponse,
+    )
+
+    return client.get(
+        {
+            "resource_id": resource_id,
+            "format": "json",
+            **kwargs,
+        }
+    )