diff --git a/CHANGELOG.md b/CHANGELOG.md index 11b0332..05b8f85 100644 --- a/CHANGELOG.md +++ b/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\_\_ diff --git a/docs/historic.md b/docs/historic.md index 00ab958..e0f6d53 100644 --- a/docs/historic.md +++ b/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 diff --git a/solcast/__init__.py b/solcast/__init__.py index 83d6f44..f92ed27 100644 --- a/solcast/__init__.py +++ b/solcast/__init__.py @@ -1,4 +1,4 @@ -__version__ = "1.2.4" +__version__ = "1.2.5" from . import ( api, diff --git a/solcast/historic.py b/solcast/historic.py index f53d6b0..4703638 100644 --- a/solcast/historic.py +++ b/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) diff --git a/solcast/live.py b/solcast/live.py index 330f38a..a85227a 100644 --- a/solcast/live.py +++ b/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). diff --git a/solcast/urls.py b/solcast/urls.py index b5738dd..8c47947 100644 --- a/solcast/urls.py +++ b/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" diff --git a/tests/test_historic.py b/tests/test_historic.py index 3670dfa..9cfc5ce 100644 --- a/tests/test_historic.py +++ b/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()