Release 1.1.0

.github/workflows/citation-sync.yml

@@ -0,0 +1,23 @@
+name: Update CITATION.cff on Tag
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  update-citation:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - uses: Adamtaranto/citation-sync-action@v1
+        with:
+          use-pull-request: true
+          target-branch: develop
+          token: ${{ secrets.GITHUB_TOKEN }}

CITATION.cff

@@ -0,0 +1,13 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+authors:
+  - family-names: "Berrisch"
+    given-names: "Jonathan"
+    orcid: "https://orcid.org/0000-0002-4944-9074"
+  - family-names: "Xu"
+    given-names: "Jie"
+    orcid: "https://orcid.org/0009-0002-1518-8010"
+title: "entsoe-apy: Python Package to Query the ENTSO-E API"
+version: 1.1.0
+date-released: 2026-05-12
+url: "https://github.com/BerriJ/entsoe-apy/releases/tag/v1.0.0"

docs/examples.md

@@ -35,6 +35,37 @@ df = DataFrame(records)
 
 See also [Utilities](./utilities.md) for more details on the utility functions.
 
+### Working with datetime and timezones
+
+The ENTSO-E API is (usually) expecting UTC timestamps but the European power markets operate on a Europe/Berlin basis. We can use the `format_entsoe_datetime` function to convert `datetime` and `pandas` timestamps in the API interface. The function handles time zone information and parses `datetime` derived types to the respective integer. Timezone-naive timestamps are assumed to be in UTC.
+
+```python
+import pandas as pd
+from entsoe.Market import EnergyPrices
+from entsoe.utils import (
+    extract_records, 
+    add_timestamps, 
+    format_entsoe_datetime
+)
+
+period_start = pd.Timestamp("2024-02-01", tz="Europe/Berlin")
+period_end = pd.Timestamp("2024-02-02", tz="Europe/Berlin")
+
+# Query energy prices
+result = EnergyPrices(
+    in_domain="10YNL----------L", # Netherlands
+    out_domain="10YNL----------L",
+    period_start=format_entsoe_datetime(period_start),
+    period_end=format_entsoe_datetime(period_end),
+).query_api()
+
+records = extract_records(result)
+records = add_timestamps(records)
+df = pd.DataFrame(records)
+df = df.convert_dtypes()
+```
+
+
 ### Extracting Specific Domains
 
 You can extract specific parts of the result by specifying a domain:

docs/utilities.md

@@ -1,3 +1,5 @@
 ::: entsoe.utils.extract_records
 
 ::: entsoe.utils.add_timestamps
+
+::: entsoe.utils.format_entsoe_datetime

misc/endpoints/Balancing/IFs mFRR 9.9, aFRR 9.6&9.8 Changes to Bid Availability Archives.json

@@ -0,0 +1,48 @@
+{
+  "name": "IFs mFRR 9.9, aFRR 9.6&9.8 Changes to Bid Availability Archives",
+  "method": "GET",
+  "query": [
+    {
+      "key": "documentType",
+      "value": "B45",
+      "description": "[M] B45 = Bid Availability Document"
+    },
+    {
+      "key": "processType",
+      "value": "A47",
+      "description": "[M] A47"
+    },
+    {
+      "key": "Domain",
+      "value": "10YDE-VE-------2",
+      "description": "[M] EIC code of a Scheduling Area or LFA"
+    },
+    {
+      "key": "periodStart",
+      "value": "202309232200",
+      "description": "[M] Pattern yyyyMMddHHmm e.g. 201601010000"
+    },
+    {
+      "key": "periodEnd",
+      "value": "202309242200",
+      "description": "[M] Pattern yyyyMMddHHmm e.g. 201601010000"
+    },
+    {
+      "key": "storageType",
+      "value": "archive",
+      "description": "[M] Used to request archives"
+    },
+    {
+      "key": "businessType",
+      "value": "C46",
+      "description": "[O] C40 = Conditional bid; C41 = Thermal limit; C42 = Frequency limit; C43 = Voltage limit; C44 = Current limit; C45 = Short-circuit current limits; C46 = Dynamic stability limit",
+      "disabled": true
+    },
+    {
+      "key": "offset",
+      "value": "100",
+      "description": "[O] Integer: Zero‑based index of the first archive to return. The offset parameter paginates the response in batches of 100 archives (e.g., offset = n returns the archives in the range n+1 to n+100).",
+      "disabled": true
+    }
+  ]
+}

misc/endpoints/Market/11.1 Continuous Allocations - Offered Transfer Capacity.json

@@ -42,12 +42,6 @@
       "value": "20240515123900",
       "description": "[O] For Offered Capacity Evolution can be quried with datetime in numeric. For example 20210803113900000 for evolution update date time 03.08.2021 13:39:00.000. If there is no OC evolution version with requested update_DateAndOrTime the system selects OC version valid in the given time (e.g., closest previous update_DateAndOrTime). The most recent publish OC version is provided in case the update_DateAndOrTime parameter is omitted. The most recent published OC version and intermediate OC versions is distinguished by document type: −   Intermediate OC values: A31 −   Most recent published OC values: B33",
       "disabled": true
-    },
-    {
-      "key": "offset",
-      "value": "0",
-      "description": "[O] Integer: Zero‑based index of the first TimeSeries to return. The offset parameter paginates the response in batches of 100 TimeSeries (e.g., offset = n returns the TimeSeries in the range n+1 to n+100).",
-      "disabled": true
     }
   ]
 }

misc/endpoints/Market/11.1.B Flow Based Allocations.json

@@ -9,27 +9,27 @@
     },
     {
       "key": "processType",
-      "value": "A33",
+      "value": "A44",
       "description": "[M] A43 = Day ahead; A44 = Intraday; A32 = Month-ahead; A33 = Year-ahead"
     },
     {
       "key": "out_Domain",
-      "value": "10Y1001A1001A91G",
+      "value": "10YDOM-REGION-1V",
       "description": "[M] EIC code of a Region"
     },
     {
       "key": "in_Domain",
-      "value": "10Y1001A1001A91G",
+      "value": "10YDOM-REGION-1V",
       "description": "[M] EIC code of a Region"
     },
     {
       "key": "periodStart",
-      "value": "202412312300",
+      "value": "201402032300",
       "description": "[M] Pattern yyyyMMddHHmm e.g. 201601010000"
     },
     {
       "key": "periodEnd",
-      "value": "202512312300",
+      "value": "201402040500",
       "description": "[M] Pattern yyyyMMddHHmm e.g. 201601010000"
     }
   ]

misc/endpoints/README.md

@@ -21,8 +21,8 @@ To regenerate this list, run:
 - [12.1.D Energy Prices](Market/12.1.D%20Energy%20Prices.json)
 
 ## [Load](Load)
-- [6.1.A Actual Total Load](Load/6.1.A%20Actual%20Total%20Load.json)
 - [6.1.A Actual Total Load - SECURITY_TOKEN in header](Load/6.1.A%20Actual%20Total%20Load%20-%20SECURITY_TOKEN%20in%20header.json)
+- [6.1.A Actual Total Load](Load/6.1.A%20Actual%20Total%20Load.json)
 - [6.1.B Day-ahead Total Load Forecast](Load/6.1.B%20Day-ahead%20Total%20Load%20Forecast.json)
 - [6.1.C Week-ahead Total Load Forecast](Load/6.1.C%20Week-ahead%20Total%20Load%20Forecast.json)
 - [6.1.D Month-ahead Total Load Forecast](Load/6.1.D%20Month-ahead%20Total%20Load%20Forecast.json)
@@ -66,6 +66,7 @@ To regenerate this list, run:
 - [12.3.B&C Balancing energy bids](Balancing/12.3.B%26C%20Balancing%20energy%20bids.json)
 - [12.3.B&C Balancing energy bids archives](Balancing/12.3.B%26C%20Balancing%20energy%20bids%20archives.json)
 - [IFs mFRR 9.9, aFRR 9.6&9.8 Changes to Bid Availability](Balancing/IFs%20mFRR%209.9%2C%20aFRR%209.6%269.8%20Changes%20to%20Bid%20Availability.json)
+- [IFs mFRR 9.9, aFRR 9.6&9.8 Changes to Bid Availability Archives](Balancing/IFs%20mFRR%209.9%2C%20aFRR%209.6%269.8%20Changes%20to%20Bid%20Availability%20Archives.json)
 - [12.3.E Aggregated Balancing Energy Bids (GL EB)](Balancing/12.3.E%20Aggregated%20Balancing%20Energy%20Bids%20%28GL%20EB%29.json)
 - [IFs 3.10, 3.16 & 3.17 Netted and Exchanged Volumes](Balancing/IFs%203.10%2C%203.16%20%26%203.17%20Netted%20and%20Exchanged%20Volumes.json)
 - [IFs 3.10, 3.16 & 3.17 Netted and Exchanged Volumes per Border](Balancing/IFs%203.10%2C%203.16%20%26%203.17%20Netted%20and%20Exchanged%20Volumes%20per%20Border.json)

misc/endpoints/all_endpoints.json

@@ -20,8 +20,8 @@
   {
     "name": "Load",
     "items": [
-      "6.1.A Actual Total Load",
       "6.1.A Actual Total Load - SECURITY_TOKEN in header",
+      "6.1.A Actual Total Load",
       "6.1.B Day-ahead Total Load Forecast",
       "6.1.C Week-ahead Total Load Forecast",
       "6.1.D Month-ahead Total Load Forecast",
@@ -77,6 +77,7 @@
       "12.3.B&C Balancing energy bids",
       "12.3.B&C Balancing energy bids archives",
       "IFs mFRR 9.9, aFRR 9.6&9.8 Changes to Bid Availability",
+      "IFs mFRR 9.9, aFRR 9.6&9.8 Changes to Bid Availability Archives",
       "12.3.E Aggregated Balancing Energy Bids (GL EB)",
       "IFs 3.10, 3.16 & 3.17 Netted and Exchanged Volumes",
       "IFs 3.10, 3.16 & 3.17 Netted and Exchanged Volumes per Border",

pyproject.toml

@@ -4,7 +4,7 @@ authors = [
   {name="Jonathan Berrisch", email="jonathan.berrisch@uni-due.de"},
   {name="Jie Xu", email="jie.xu@uni-due.de"}
 ]
-version = "1.0.0"
+version = "1.1.0"
 description = "A Python library for accessing ENTSO-E Transparency Platform API endpoints"
 readme = "README.md"
 license = "GPL-3.0-or-later"

src/entsoe/Balancing/__init__.py

@@ -12,6 +12,7 @@
     BalancingEnergyBids,
     BalancingEnergyBidsArchives,
     ChangesToBidAvailability,
+    ChangesToBidAvailabilityArchives,
     CrossBorderMarginalPricesForAFRR,
     CurrentBalancingState,
     ElasticDemands,
@@ -43,6 +44,7 @@
     "BalancingEnergyBidsArchives",
     "BalancingEnergyBids",
     "ChangesToBidAvailability",
+    "ChangesToBidAvailabilityArchives",
     "CrossBorderMarginalPricesForAFRR",
     "CurrentBalancingState",
     "ElasticDemands",

src/entsoe/Balancing/specific_params.py

@@ -1183,6 +1183,68 @@ def __init__(
         )
 
 
+class ChangesToBidAvailabilityArchives(Balancing):
+    """Parameters for IFs mFRR 9.9, aFRR 9.6&9.8 Changes to Bid Availability Archives.
+
+    Data view:
+    https://transparency.entsoe.eu/balancing/r2/changesToBidAvailability/show
+
+    Fixed parameters:
+
+    - documentType: B45 (Bid Availability Document)
+    - processType: A47 (Manual frequency restoration reserve)
+    - storageType: archive
+
+    Optional parameters:
+    - businessType: C40=Conditional bid, C41=Thermal limit, C42=Frequency limit,
+                   C43=Voltage limit, C44=Current limit,
+                   C45=Short-circuit current limits,
+                   C46=Dynamic stability limit
+
+    Notes:
+    - This is the archived version of changes to bid availability
+    - The offset parameter paginates the response in batches of 100 archives
+    """
+
+    code = "IF_mFRR_aFRR_9.6_9.8_9.9_Archives"
+
+    def __init__(
+        self,
+        period_start: int,
+        period_end: int,
+        domain: str,
+        # Optional balancing-specific parameters
+        business_type: Optional[str] = None,
+        # Additional common parameters
+        offset: int = 0,
+    ):
+        """
+        Initialize changes to bid availability archives parameters.
+
+        Args:
+            period_start: Start period (YYYYMMDDHHMM format)
+            period_end: End period (YYYYMMDDHHMM format)
+            domain: EIC code of Scheduling Area or LFA
+            business_type: C40=Conditional bid, C41=Thermal limit, C42=Frequency limit,
+                          C43=Voltage limit, C44=Current limit, C45=Short-circuit limit,
+                          C46=Dynamic stability limit
+            offset: Zero-based index of the first archive to return (batches of 100)
+        """
+        # Initialize with preset and user parameters
+        super().__init__(
+            document_type="B45",
+            period_start=period_start,
+            period_end=period_end,
+            domain=domain,
+            process_type="A47",
+            business_type=business_type,
+            offset=offset,
+        )
+
+        # Add the storageType parameter specific to archives endpoint
+        self.add_optional_param("storageType", "archive")
+
+
 class BalancingBorderCapacityLimitations(Balancing):
     """Parameters for IFs 4.3 & 4.4 Balancing Border Capacity Limitations.
 

src/entsoe/utils/__init__.py

@@ -1,5 +1,12 @@
 from .mappings_dict import mappings
 from .records import extract_records
 from .timestamps import add_timestamps, calculate_timestamp
+from .utils import format_entsoe_datetime
 
-__all__ = ["mappings", "extract_records", "add_timestamps", "calculate_timestamp"]
+__all__ = [
+    "mappings",
+    "extract_records",
+    "add_timestamps",
+    "calculate_timestamp",
+    "format_entsoe_datetime",
+]

src/entsoe/utils/records.py

@@ -69,14 +69,18 @@ def _filter_ignored_fields(record: Dict[str, Any]) -> Dict[str, Any]:
         return {k: v for k, v in record.items() if k not in ignore_fields}
 
     if isinstance(data, dict):
-        items = {}
+        items: Dict[str, Any] = {}
+        expansions: List[List[Dict[str, Any]]] = []
         for k, v in data.items():
             new_key = f"{parent_key}{sep}{k}" if parent_key else k
             if isinstance(v, dict):
                 sub_records = normalize_to_records(
                     v, new_key, sep=sep, ignore_fields=ignore_fields
                 )
-                items.update(sub_records[0])  # merge dict
+                if len(sub_records) == 1:
+                    items.update(sub_records[0])
+                elif len(sub_records) > 1:
+                    expansions.append(sub_records)
             elif isinstance(v, list):
                 # Expand list elements into multiple records
                 list_records = []
@@ -88,14 +92,15 @@ def _filter_ignored_fields(record: Dict[str, Any]) -> Dict[str, Any]:
                         list_records.extend(sub_records)
                     else:
                         list_records.append({new_key: elem})
-                # Cross join if multiple records, else just keep one
                 if list_records:
-                    return [
-                        _filter_ignored_fields(dict(items, **lr)) for lr in list_records
-                    ]
+                    expansions.append(list_records)
             else:
                 items[new_key] = v
-        return [_filter_ignored_fields(items)]
+        # Cross-join base items with all collected expansions
+        result: List[Dict[str, Any]] = [items]
+        for expansion in expansions:
+            result = [dict(r, **e) for r in result for e in expansion]
+        return [_filter_ignored_fields(r) for r in result]
     elif isinstance(data, list):
         records = []
         for elem in data:

src/entsoe/utils/utils.py

@@ -1,4 +1,4 @@
-from datetime import datetime, timedelta
+from datetime import datetime, timedelta, timezone
 import inspect
 from xml.etree import ElementTree as ET
 
@@ -31,13 +31,24 @@ def format_entsoe_datetime(dt: datetime) -> int:
     """
     Format datetime object to ENTSOE datetime format (YYYYMMDDHHMM).
 
+    Convert a (tz-aware) datetime to UTC and format it as an integer in the
+    ENTSOE format. If the datetime is naive, it is assumed to be in UTC. This
+    function can be used to convert pd.Timestamp and pl.Datetime objects to the
+    required format for ENTSOE API calls. Please have a look at the
+    documentation for more details and examples.
+
     Args:
         dt: datetime object
 
     Returns:
         Date in YYYYMMDDHHMM format as integer
     """
-    return int(dt.strftime("%Y%m%d%H%M"))
+    if dt.tzinfo is not None:
+        utc_timestamp = dt.astimezone(timezone.utc)
+        return int(utc_timestamp.strftime("%Y%m%d%H%M"))
+    else:
+        # Assume naive timestamps are in UTC
+        return int(dt.strftime("%Y%m%d%H%M"))
 
 
 def check_date_range_limit(