Add historic advanced pv power (#38)

* Add historic advanced pv power

* Bump version to 1.2.5

---------

Co-authored-by: Lachlan <lachlan@solcast.com.au>

Author: lachlan-solcast

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## [1.2.5] - 2024-07-05
+
+- Add advanced_pv_power to the historic module
+
 ## [1.2.4] - 2024-04-19
 
 - Add pv_power_sites to package \_\_init\_\_

docs/historic.md

@@ -2,12 +2,13 @@
 
 Historical irradiance, weather and power data, from 2007 to 7 days ago at 1-2km and 5 minutes resolution.
 For more information see the [API Docs](https://docs.solcast.com.au/#36bffd5d-d2b5-4bc3-b757-855624432375). 
-The `Historic` module has 2 methods:
+The `Historic` module has 3 methods:
 
 | Endpoint                | API Docs                                                                                                |
 |-------------------------|---------------------------------------------------------------------------------------------------------|
 | `radiation_and_weather` | [list of API parameters](https://docs.solcast.com.au/#9de907e7-a52f-4993-a0f0-5cffee78ad10){.md-button} |
 | `rooftop_pv_power`      | [list of API parameters](https://docs.solcast.com.au/#504e6e52-992f-4ac2-a4dc-d7ab312f992a){.md-button}                |
+| `advanced_pv_power`     | [list of API parameters](https://docs.solcast.com.au/#1db1132e-8d49-4f25-939f-34883e5336c4){.md-button}               |
 
 ### Example
 

solcast/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "1.2.4"
+__version__ = "1.2.5"
 
 from . import (
     api,

solcast/historic.py

@@ -1,5 +1,10 @@
 from .api import Client, PandafiableResponse
-from .urls import base_url, historic_radiation_and_weather, historic_rooftop_pv_power
+from .urls import (
+    base_url,
+    historic_radiation_and_weather,
+    historic_rooftop_pv_power,
+    historic_advanced_pv_power,
+)
 
 
 def radiation_and_weather(
@@ -99,3 +104,46 @@ def rooftop_pv_power(
         params["duration"] = duration
 
     return client.get(params)
+
+
+def advanced_pv_power(
+    resource_id: int, start: str, end: str = None, duration: str = None, **kwargs
+) -> PandafiableResponse:
+    """
+    Get historical high spec PV power estimated actuals for the requested site,
+    derived from satellite (clouds and irradiance over non-polar continental areas)
+    and numerical weather models (other data).
+
+    Args:
+        resource_id: a Solcast resource id
+        start: datetime-like, first day of the requested period
+        end: optional, datetime-like, last day of the requested period
+        duration: optional, ISO_8601 compliant duration for the historic data.
+            Must be within 31 days of the start_date.
+        **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=historic_advanced_pv_power,
+        response_type=PandafiableResponse,
+    )
+
+    assert (end is None and duration is not None) | (
+        duration is None and end is not None
+    ), "only one of duration or end"
+
+    params = {
+        "resource_id": resource_id,
+        "start": start,
+        "format": "json",
+        **kwargs,
+    }
+
+    if end is not None:
+        params["end"] = end
+    if duration is not None:
+        params["duration"] = duration
+
+    return client.get(params)

solcast/live.py

@@ -46,7 +46,7 @@ def radiation_and_weather(
 def rooftop_pv_power(
     latitude: float, longitude: float, **kwargs
 ) -> PandafiableResponse:
-    """Get basic rooftop PV power forecasts from the present time up to 14 days ahead
+    """Get basic rooftop PV power estimated actuals 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).
@@ -71,7 +71,7 @@ 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
+    Get high spec PV power estimated actuals 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).

solcast/urls.py

@@ -4,6 +4,7 @@
 live_advanced_pv_power = "data/live/advanced_pv_power"
 historic_radiation_and_weather = "data/historic/radiation_and_weather"
 historic_rooftop_pv_power = "data/historic/rooftop_pv_power"
+historic_advanced_pv_power = "data/historic/advanced_pv_power"
 forecast_radiation_and_weather = "data/forecast/radiation_and_weather"
 forecast_rooftop_pv_power = "data/forecast/rooftop_pv_power"
 forecast_advanced_pv_power = "data/forecast/advanced_pv_power"

tests/test_historic.py

@@ -1,7 +1,10 @@
 import pytest
 
 from solcast import historic
-from solcast.unmetered_locations import load_test_locations_coordinates
+from solcast.unmetered_locations import (
+    load_test_locations_coordinates,
+    UNMETERED_LOCATIONS,
+)
 import pandas as pd
 
 
@@ -38,3 +41,15 @@ def test_rooftop_pv_power():
     assert res.success is True
     assert len(res.to_dict()["estimated_actuals"]) == 3 * 48 + 1
     assert ~res.to_pandas().isna().any().all()
+
+
+def test_advanced_pv_power():
+    res = historic.advanced_pv_power(
+        resource_id=UNMETERED_LOCATIONS["Sydney Opera House"]["resource_id"],
+        start="2022-10-25T14:45:00.00Z",
+        duration="P3D",
+    )
+
+    assert res.success is True
+    assert len(res.to_dict()["estimated_actuals"]) == 3 * 48 + 1
+    assert ~res.to_pandas().isna().any().all()