feature: adding aggregations (#39)

adds module to fetch from the aggregations endpoint.

Author: lorenzo-solcast

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## [1.3.0] - 2024-07-10
+
+- Add the `aggregations` module. No tests as we are yet to expose unmetered aggregations. 
+
+
 ## [1.2.5] - 2024-07-05
 
 - Add advanced_pv_power to the historic module

docs/aggregrations.md

@@ -0,0 +1,31 @@
+# Aggregations
+More information in the [API Docs](https://docs.solcast.com.au/?#c1726d91-8a67-4803-89f4-02ecb5f03c05).
+
+The module `aggregations` has 2 available methods:
+
+| Endpoint            | API Docs                                                                                                |
+|---------------------|---------------------------------------------------------------------------------------------------------|
+| `live`              | [details](https://docs.solcast.com.au/#d1fc6dfa-a2f6-40db-a2b4-545030e33197){.md-button} |
+| `forecast`          | [details](https://docs.solcast.com.au/#bda5d3ea-34fb-4f36-b0ca-d0a2d7c00629){.md-button}               |
+
+### Example
+
+```python
+from solcast import aggregations
+
+res = aggregations.forecast(
+    collection_id="country_total",
+    aggregation_id="it_total",
+    output_parameters=['percentage', 'pv_estimate']
+)
+
+res.to_pandas().head()
+```
+
+| period_end                |   percentage |   pv_estimate |
+|:--------------------------|-------------:|--------------:|
+| 2024-06-13 04:30:00+00:00 |          1   |       333.499 |
+| 2024-06-13 05:00:00+00:00 |          3.6 |      1157.39  |
+| 2024-06-13 05:30:00+00:00 |          7   |      2268.41  |
+| 2024-06-13 06:00:00+00:00 |         10.4 |      3361.17  |
+| 2024-06-13 06:30:00+00:00 |         14.4 |      4630.91  |

docs/index.md

@@ -66,13 +66,14 @@ df = res.to_dict()
 
 Available modules are 
 
-| Module       | API Docs                        |
-|--------------|---------------------------------|
-| `live`       | [solcast.live](live.md)           |
-| `historic` | [solcast.historic](historic.md) |
-| `forecast`   | [solcast.forecast](forecast.md)   |
-| `tmy`        | [solcast.tmy](tmy.md)             |
+| Module           | API Docs                                 |
+|------------------|------------------------------------------|
+| `live`           | [solcast.live](live.md)                  |
+| `historic`       | [solcast.historic](historic.md)          |
+| `forecast`       | [solcast.forecast](forecast.md)          |
+| `tmy`            | [solcast.tmy](tmy.md)                    |
 | `pv_power_sites` | [solcast.pv_power_sites](pv_power_sites) |
+| `aggregations`   | [solcast.aggregations](aggregations)     |
 
 
 ## Docs

mkdocs.yml

@@ -15,6 +15,7 @@ nav:
   - Historic: historic.md
   - TMY: tmy.md
   - PV Power Sites: pv_power_sites.md
+  - Aggregations: aggregations.md
   - Example Notebooks:
       - '1.1 Getting Data: Historic Solar Radiation': 'notebooks/1.1 Getting Data - Historic Solar Radiation.ipynb'
       - '1.2 Getting Data: TMY in your local timezone': 'notebooks/1.2 Getting Data - TMY in your local timezone.ipynb'

solcast/__init__.py

@@ -1,17 +1,19 @@
-__version__ = "1.2.5"
+__version__ = "1.3.0"
 
 from . import (
     api,
     forecast,
     historic,
     live,
     tmy,
+    aggregations,
     unmetered_locations,
     urls,
     pv_power_sites,
 )
 
 __all__ = [
+    "aggregations",
     "forecast",
     "historic",
     "live",

solcast/aggregations.py

@@ -0,0 +1,66 @@
+from typing import Optional
+
+from .api import Client, PandafiableResponse
+from .urls import (
+    base_url,
+    forecast_grid_aggregations,
+    live_grid_aggregations,
+)
+
+
+def live(
+    collection_id: str, aggregation_id: Optional[str], **kwargs
+) -> PandafiableResponse:
+    """
+    Get live aggregation data for up to 7 days of data at a time for a requested collection or aggregation.
+
+    Args:
+        collection_id: a unique identifier for your collection.
+        aggregation_id: a unique identifier that belongs to the requested collection.
+        **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=live_grid_aggregations,
+        response_type=PandafiableResponse,
+    )
+
+    return client.get(
+        {
+            "collection_id": collection_id,
+            "aggregation_id": aggregation_id,
+            "format": "json",
+            **kwargs,
+        }
+    )
+
+
+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.
+
+    Args:
+        collection_id: a unique identifier for your collection.
+        aggregation_id: a unique identifier that belongs to the requested collection.
+        **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_grid_aggregations,
+        response_type=PandafiableResponse,
+    )
+
+    return client.get(
+        {
+            "collection_id": collection_id,
+            "aggregation_id": aggregation_id,
+            "format": "json",
+            **kwargs,
+        }
+    )

solcast/urls.py

@@ -2,12 +2,14 @@
 live_radiation_and_weather = "data/live/radiation_and_weather"
 live_rooftop_pv_power = "data/live/rooftop_pv_power"
 live_advanced_pv_power = "data/live/advanced_pv_power"
+live_grid_aggregations = "data/live/aggregations"
 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"
+forecast_grid_aggregations = "data/forecast/aggregations"
 tmy_radiation_and_weather = "data/tmy/radiation_and_weather"
 tmy_rooftop_pv_power = "data/tmy/rooftop_pv_power"
 pv_power_site = "resources/pv_power_site"