esett_soap_api

This is a wrapper to communicate with the eSett SOAP API.

SoapApiClient

Client for the eSett SOAP API.

Uses WS-Security with UsernameToken for authentication and exposes methods for interacting with the eSett services.

Docs: https://www.esett.com/app/uploads/2025/09/Information-Service-Guide.pdf

Example

from datetime import datetime
from from physical_operations_utils.esett_utils.eSettSoapApi import SoapApiClient

api = SoapApiClient(area="FI")
start = datetime(2023, 3, 27)
end = datetime(2023, 3, 29)
df_spot = api.get_imbalance_adjustments(start_time_utc=start, end_time_utc=end, time_resolution="PT15M")

Source code in physical_operations_utils/esett_utils/eSettSoapApi.py

class SoapApiClient:
    """
    Client for the eSett SOAP API.

    Uses WS-Security with UsernameToken for authentication and exposes methods for
    interacting with the eSett services.

    **Docs:** https://www.esett.com/app/uploads/2025/09/Information-Service-Guide.pdf

    Example:
        ```python
        from datetime import datetime
        from from physical_operations_utils.esett_utils.eSettSoapApi import SoapApiClient

        api = SoapApiClient(area="FI")
        start = datetime(2023, 3, 27)
        end = datetime(2023, 3, 29)
        df_spot = api.get_imbalance_adjustments(start_time_utc=start, end_time_utc=end, time_resolution="PT15M")
        ```
    """

    # Valid time resolutions according to ISO 8601 duration format
    VALID_TIME_RESOLUTIONS = {
        "PT15M",  # 15 minutes
        "PT30M",  # 30 minutes
        "PT1H",  # 1 hour
        "P1D",  # 1 day
    }

    # Valid market areas where eSett SOAP API data can be fetched
    VALID_AREAS = {
        "SE",  # Sweden
        "FI",  # Finland
        "NO",  # Norway
    }

    def __init__(
        self, username: str = None, password: str = None, area: str = None
    ) -> None:
        """
        Initialize the API client.

        Args:
            username: eSett account username. If `None`, read from keys file.
            password: eSett account password or Azure Key Vault secret value. If `None`, read from keys file.
            area: Market area code (e.g., `"SE"`, `"FI"`, `"NO"`).

        Raises:
            urllib.error.URLError: If token request fails.
            KeyError: If required keys are missing from configuration.
            ValueError: If area is not one of the supported market areas.

        Example:
            ```python
            from physical_operations_utils.esett_utils.eSettSoapApi import SoapApiClient
            api = SoapApiClient(area="FI")  # pulls credentials from the keys file/Azure Key Vault
            ```
        """
        # Validate area parameter
        if area is not None and area not in self.VALID_AREAS:
            raise ValueError(
                f"Invalid area '{area}'. Must be one of: {', '.join(sorted(self.VALID_AREAS))}"
            )

        self.coding_scheme = {
            "EIC": "A01",  # EIC
            "FI": "A10",  # GS1
            "SE": "NSE",  # National Sweden
            "NO": "A10",  # National Norway
            "DK": "NDK",  # National Denmark
        }

        self.sender_indentification = {
            "FI": "6430076111111",
            "SE": "14600",
            "NO": "7080005010788",
            "DK": "5790000000031",
        }

        self.credentials = {
            "SE": "eSett_SOAP_API_SE",
            "FI": "eSett_SOAP_API_FI",
            "NO": "eSett_SOAP_API_NO",
        }

        keys = get_keys_yaml_file().get(self.credentials[area])

        if username is None:
            username = keys["username"]
        if password is None:
            secret = keys["secret"]
            password = get_secret(secret)

        self.area = area

        self.wsdl_url = "https://service.esett.com/INFS/InformationService.svc?wsdl"

        self.client = Client(wsdl=self.wsdl_url, wsse=UsernameToken(username, password))

    def _validate_time_resolution(self, time_resolution: str) -> None:
        """
        Validate time resolution parameter.

        Args:
            time_resolution: ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.

        Raises:
            ValueError: If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.
        """
        if time_resolution not in self.VALID_TIME_RESOLUTIONS:
            raise ValueError(
                f"Invalid time_resolution '{time_resolution}'. Must be one of: {', '.join(sorted(self.VALID_TIME_RESOLUTIONS))}"
            )

    def _validate_datetime_parameters(
        self, start_time_utc: datetime, end_time_utc: datetime
    ) -> None:
        """
        Validate datetime parameters for API methods.

        Args:
            start_time_utc: Start time in UTC (tz-aware datetime).
            end_time_utc: End time in UTC (tz-aware datetime).

        Raises:
            ValueError: If datetime parameters are invalid (not UTC or start >= end).
        """
        validate_datetime_in_utc(start_time_utc)
        validate_datetime_in_utc(end_time_utc)
        validate_start_time_before_end_time(start_time_utc, end_time_utc)

    def get_imbalance_adjustments(
        self, start_time_utc: datetime, end_time_utc: datetime, time_resolution: str
    ) -> Any:
        """
        Fetch **Imbalance Adjustment (IBA)** data for a specified time period.

        Returns raw SOAP response containing imbalance adjustment information used for
        settlement calculations in the Nordic electricity market.

        Args:
            start_time_utc: Start time in UTC (tz-aware datetime).
            end_time_utc: End time in UTC (tz-aware datetime).
            time_resolution: ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.

        Returns:
            SOAP response object containing imbalance adjustment data.

        Raises:
            Exception: If SOAP service call fails.
            ValueError: If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

        Example:
            ```python
            from datetime import datetime, timezone
            api = SoapApiClient(area="FI")
            result = api.get_imbalance_adjustments(
                start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
                end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
                time_resolution="PT15M"
            )
            ```
        """
        # Validate input parameters
        self._validate_datetime_parameters(start_time_utc, end_time_utc)
        self._validate_time_resolution(time_resolution)

        sender_coding = self.coding_scheme[self.area]
        sender_id = self.sender_indentification[self.area]
        request = {
            "DocumentIdentification": {"v": "1"},
            "DocumentType": {"v": "A25"},
            "SenderIdentification": {
                "v": f"{sender_id}",
                "codingScheme": f"{sender_coding}",
            },
            "SenderRole": {"v": "A08"},
            "ReceiverIdentification": {"v": " ", "codingScheme": "A01"},
            "ReceiverRole": {"v": "A05"},
            "CreationDateTime": {
                "v": datetime.now(timezone.utc)
                .replace(microsecond=0)
                .strftime("%Y-%m-%dT%H:%M:%SZ")
            },
            "RequestComponent": [
                {
                    "RequestedAttribute": {"v": "DataFlow"},
                    "RequestedAttributeValue": {"v": "IBA"},
                },
                {
                    "RequestedAttribute": {"v": "TimeInterval"},
                    "RequestedAttributeValue": {
                        "v": f"{start_time_utc.isoformat()}Z/{end_time_utc.isoformat()}Z"
                    },
                },
                {
                    "RequestedAttribute": {"v": "TimeResolution"},
                    "RequestedAttributeValue": {"v": f"{time_resolution}"},
                },
            ],
        }
        return self.client.service.GetData(request=request)

    def get_activated_reserves(
        self,
        start_time_utc: datetime,
        end_time_utc: datetime,
        time_resolution: str,
        business_type: str,
        reason_code: str,
        reason_code_2: Optional[str] = None,
        regulation_object: Optional[str] = None,
        mba: Optional[str] = None,
    ) -> Any:
        """
        Fetch **Activated Reserves (ACR)** data for frequency regulation and balancing services.

        Retrieves information about reserves that were activated to maintain system balance,
        including both upward and downward regulation volumes and associated costs.

        Args:
            start_time_utc: Start time in UTC (tz-aware datetime).
            end_time_utc: End time in UTC (tz-aware datetime).
            time_resolution: ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.
            business_type: Business type code (e.g., `"A95"` for frequency restoration).
            reason_code: Primary reason code for activation (e.g., `"A01"`).
            reason_code_2: Optional secondary reason code for activation.
            regulation_object: Optional specific regulation object identifier.
            mba: Optional Metering Balance Area identifier.

        Returns:
            SOAP response object containing activated reserves data.

        Raises:
            Exception: If SOAP service call fails.
            ValueError: If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

        Example:
            ```python
            from datetime import datetime, timezone
            api = SoapApiClient(area="FI")
            result = api.get_activated_reserves(
                start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
                end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
                time_resolution="PT1H",
                business_type="A95",
                reason_code="A01",
                reason_code_2="A02",
                mba="SE_MBA_001"
            )
            ```
        """
        # Validate input parameters
        self._validate_datetime_parameters(start_time_utc, end_time_utc)
        self._validate_time_resolution(time_resolution)
        sender_coding = self.coding_scheme[self.area]
        sender_id = self.sender_indentification[self.area]
        rc_list = [
            {
                "RequestedAttribute": {"v": "DataFlow"},
                "RequestedAttributeValue": {"v": "ACR"},
            },
            {
                "RequestedAttribute": {"v": "TimeInterval"},
                "RequestedAttributeValue": {
                    "v": f"{start_time_utc.isoformat()}Z/{end_time_utc.isoformat()}Z"
                },
            },
            {
                "RequestedAttribute": {"v": "TimeResolution"},
                "RequestedAttributeValue": {"v": f"{time_resolution}"},
            },
            {
                "RequestedAttribute": {"v": "BusinessType"},
                "RequestedAttributeValue": {"v": f"{business_type}"},
            },
            {
                "RequestedAttribute": {"v": "ReasonCode"},
                "RequestedAttributeValue": {"v": f"{reason_code}"},
            },
        ]
        if reason_code_2:
            rc_list.append(
                {
                    "RequestedAttribute": {"v": "ReasonCode"},
                    "RequestedAttributeValue": {"v": f"{reason_code_2}"},
                }
            )
        if regulation_object:
            rc_list.append(
                {
                    "RequestedAttribute": {"v": "RegulationObject"},
                    "RequestedAttributeValue": {
                        "v": f"{regulation_object}",
                        "codingScheme": f"{sender_coding}",
                    },
                }
            )
        if mba:
            rc_list.append(
                {
                    "RequestedAttribute": {"v": "MBA"},
                    "RequestedAttributeValue": {"v": f"{mba}", "codingScheme": "A01"},
                }
            )

        request = {
            "DocumentIdentification": {"v": "1"},
            "DocumentType": {"v": "A25"},
            "SenderIdentification": {
                "v": f"{sender_id}",
                "codingScheme": f"{sender_coding}",
            },
            "SenderRole": {
                "v": "A08"
            },  # Use "A46" if you must act as BSP after BSP go-live window【60-22】
            "ReceiverIdentification": {"v": " ", "codingScheme": "A01"},
            "ReceiverRole": {"v": "A05"},
            "CreationDateTime": {
                "v": datetime.now(timezone.utc)
                .replace(microsecond=0)
                .strftime("%Y-%m-%dT%H:%M:%SZ")
            },
            "RequestComponent": rc_list,
        }
        return self.client.service.GetData(request=request)

    def get_capacity_reserves(
        self,
        start_time_utc: datetime,
        end_time_utc: datetime,
        time_resolution: str,
        business_type: str,
        reason_code: str,
        mba: Optional[str] = None,
    ) -> Any:
        """
        Fetch **Capacity Reserves (CRE)** data for reserve capacity procurement and allocation.

        Retrieves information about reserved capacity that is procured by TSOs for
        maintaining system security and balance, including capacity volumes and prices.

        Args:
            start_time_utc: Start time in UTC (tz-aware datetime).
            end_time_utc: End time in UTC (tz-aware datetime).
            time_resolution: ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.
            business_type: Business type code (e.g., `"A95"` for frequency restoration).
            reason_code: Reason code for capacity reservation (e.g., `"A01"`).
            mba: Optional Metering Balance Area identifier.

        Returns:
            SOAP response object containing capacity reserves data.

        Raises:
            Exception: If SOAP service call fails.
            ValueError: If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

        Example:
            ```python
            from datetime import datetime, timezone
            api = SoapApiClient(area="FI")
            result = api.get_capacity_reserves(
                start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
                end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
                time_resolution="PT1H",
                business_type="A95",
                reason_code="A01",
                mba="NO_MBA_001"
            )
            ```
        """
        # Validate input parameters
        self._validate_datetime_parameters(start_time_utc, end_time_utc)
        self._validate_time_resolution(time_resolution)

        sender_coding = self.coding_scheme[self.area]
        sender_id = self.sender_indentification[self.area]
        rc_list = [
            {
                "RequestedAttribute": {"v": "DataFlow"},
                "RequestedAttributeValue": {"v": "CRE"},
            },
            {
                "RequestedAttribute": {"v": "TimeInterval"},
                "RequestedAttributeValue": {
                    "v": f"{start_time_utc.isoformat()}Z/{end_time_utc.isoformat()}Z"
                },
            },
            {
                "RequestedAttribute": {"v": "TimeResolution"},
                "RequestedAttributeValue": {"v": f"{time_resolution}"},
            },
            {
                "RequestedAttribute": {"v": "BusinessType"},
                "RequestedAttributeValue": {"v": f"{business_type}"},
            },
            {
                "RequestedAttribute": {"v": "ReasonCode"},
                "RequestedAttributeValue": {"v": f"{reason_code}"},
            },
        ]
        if mba:
            rc_list.append(
                {
                    "RequestedAttribute": {"v": "MBA"},
                    "RequestedAttributeValue": {"v": f"{mba}", "codingScheme": "A01"},
                }
            )

        request = {
            "DocumentIdentification": {"v": "1"},
            "DocumentType": {"v": "A25"},
            "SenderIdentification": {
                "v": f"{sender_id}",
                "codingScheme": f"{sender_coding}",
            },
            "SenderRole": {"v": "A08"},  # "A46" if BSP context applies【60-25】
            "ReceiverIdentification": {"v": " ", "codingScheme": "A01"},
            "ReceiverRole": {"v": "A05"},
            "CreationDateTime": {
                "v": datetime.now(timezone.utc)
                .replace(microsecond=0)
                .strftime("%Y-%m-%dT%H:%M:%SZ")
            },
            "RequestComponent": rc_list,
        }
        return self.client.service.GetData(request=request)

    def get_merged_production(
        self,
        start_time_utc: datetime,
        end_time_utc: datetime,
        time_resolution: str,
        party_re: Optional[str] = None,
        party_re_scheme: str = "A12",
        mba: Optional[str] = None,
        asset_type: Optional[str] = None,
        production_type: Optional[str] = None,
    ) -> Any:
        """
        Fetch **Merged Production (MPR)** data aggregated across multiple production units.

        Retrieves consolidated production data that combines output from multiple generation
        units, typically used for settlement and grid balancing calculations.

        Args:
            start_time_utc: Start time in UTC (tz-aware datetime).
            end_time_utc: End time in UTC (tz-aware datetime).
            time_resolution: ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.
            party_re: Optional responsible entity (retailer) identifier.
            party_re_scheme: Coding scheme for party_re (default `"A12"`).
            mba: Optional Metering Grid Area identifier.
            asset_type: Optional asset type filter (e.g., `"WIND"`, `"SOLAR"`).
            production_type: Optional production type filter (e.g., `"RENEWABLE"`).

        Returns:
            SOAP response object containing merged production data.

        Raises:
            Exception: If SOAP service call fails.
            ValueError: If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

        Example:
            ```python
            from datetime import datetime, timezone
            api = SoapApiClient(area="FI")
            result = api.get_merged_production(
                start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
                end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
                time_resolution="PT1H",
            party_re="PARTY123",
            asset_type="WIND",
            production_type="RENEWABLE"
            )
            ```
        """
        # Validate input parameters
        self._validate_datetime_parameters(start_time_utc, end_time_utc)
        self._validate_time_resolution(time_resolution)
        sender_coding = self.coding_scheme[self.area]
        sender_id = self.sender_indentification[self.area]
        rc_list = [
            {
                "RequestedAttribute": {"v": "DataFlow"},
                "RequestedAttributeValue": {"v": "MPR"},
            },
            {
                "RequestedAttribute": {"v": "TimeInterval"},
                "RequestedAttributeValue": {
                    "v": f"{start_time_utc.isoformat()}Z/{end_time_utc.isoformat()}Z"
                },
            },
            {
                "RequestedAttribute": {"v": "TimeResolution"},
                "RequestedAttributeValue": {"v": f"{time_resolution}"},
            },
        ]
        if party_re:
            rc_list.append(
                {
                    "RequestedAttribute": {"v": "PartyRE"},
                    "RequestedAttributeValue": {
                        "v": f"{party_re}",
                        "codingScheme": f"{party_re_scheme}",
                    },
                }
            )
        if mba:
            rc_list.append(
                {
                    "RequestedAttribute": {"v": "MGA"},
                    "RequestedAttributeValue": {"v": f"{mba}", "codingScheme": "A01"},
                }
            )
        if asset_type:
            rc_list.append(
                {
                    "RequestedAttribute": {"v": "AssetType"},
                    "RequestedAttributeValue": {"v": f"{asset_type}"},
                }
            )
        if production_type:
            rc_list.append(
                {
                    "RequestedAttribute": {"v": "Production Type"},
                    "RequestedAttributeValue": {"v": f"{production_type}"},
                }
            )

        request = {
            "DocumentIdentification": {"v": "1"},
            "DocumentType": {"v": "A25"},
            "SenderIdentification": {
                "v": f"{sender_id}",
                "codingScheme": f"{sender_coding}",
            },
            "SenderRole": {"v": "A08"},
            "ReceiverIdentification": {"v": " ", "codingScheme": "A01"},
            "ReceiverRole": {"v": "A05"},
            "CreationDateTime": {
                "v": datetime.now(timezone.utc)
                .replace(microsecond=0)
                .strftime("%Y-%m-%dT%H:%M:%SZ")
            },
            "RequestComponent": rc_list,
        }
        return self.client.service.GetData(request=request)

    def get_bilateral_trades(
        self,
        start_time_utc: datetime,
        end_time_utc: datetime,
        time_resolution: str,
        in_brp: Optional[str] = None,
        out_brp: Optional[str] = None,
        agreement_id: Optional[str] = None,
        mba: Optional[str] = None,
        brp_scheme: str = "A01",
    ) -> Any:
        """
        Fetch **Bilateral Trades (BIT)** data for direct energy trading between parties.

        Retrieves information about bilateral energy transactions between balance responsible
        parties, including trade volumes, prices, and settlement details.

        Args:
            start_time_utc: Start time in UTC (tz-aware datetime).
            end_time_utc: End time in UTC (tz-aware datetime).
            time_resolution: ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.
            in_brp: Optional incoming Balance Responsible Party identifier.
            out_brp: Optional outgoing Balance Responsible Party identifier.
            agreement_id: Optional bilateral agreement identifier.
            mba: Optional Metering Balance Area identifier.
            brp_scheme: Coding scheme for BRP identifiers (default `"A01"`).

        Returns:
            SOAP response object containing bilateral trades data.

        Raises:
            Exception: If SOAP service call fails.
            ValueError: If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

        Example:
            ```python
            from datetime import datetime, timezone
            api = SoapApiClient(area="FI")
            result = api.get_bilateral_trades(
                start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
                end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
                time_resolution="PT1H",
            in_brp="BRP_001",
            out_brp="BRP_002",
            agreement_id="BILATERAL_123"
            )
            ```
        """
        # Validate input parameters
        self._validate_datetime_parameters(start_time_utc, end_time_utc)
        self._validate_time_resolution(time_resolution)
        sender_coding = self.coding_scheme[self.area]
        sender_id = self.sender_indentification[self.area]
        rc_list = [
            {
                "RequestedAttribute": {"v": "DataFlow"},
                "RequestedAttributeValue": {"v": "BIT"},
            },
            {
                "RequestedAttribute": {"v": "TimeInterval"},
                "RequestedAttributeValue": {
                    "v": f"{start_time_utc.isoformat()}Z/{end_time_utc.isoformat()}Z"
                },
            },
            {
                "RequestedAttribute": {"v": "TimeResolution"},
                "RequestedAttributeValue": {"v": f"{time_resolution}"},
            },
        ]
        if in_brp:
            rc_list.append(
                {
                    "RequestedAttribute": {"v": "InBRP"},
                    "RequestedAttributeValue": {
                        "v": f"{in_brp}",
                        "codingScheme": f"{brp_scheme}",
                    },
                }
            )
        if out_brp:
            rc_list.append(
                {
                    "RequestedAttribute": {"v": "OutBRP"},
                    "RequestedAttributeValue": {
                        "v": f"{out_brp}",
                        "codingScheme": f"{brp_scheme}",
                    },
                }
            )
        if agreement_id:
            rc_list.append(
                {
                    "RequestedAttribute": {"v": "AgreementID"},
                    "RequestedAttributeValue": {"v": f"{agreement_id}"},
                }
            )
        if mba:
            rc_list.append(
                {
                    "RequestedAttribute": {"v": "MBA"},
                    "RequestedAttributeValue": {"v": f"{mba}", "codingScheme": "A01"},
                }
            )

        request = {
            "DocumentIdentification": {"v": "1"},
            "DocumentType": {"v": "A25"},
            "SenderIdentification": {
                "v": f"{sender_id}",
                "codingScheme": f"{sender_coding}",
            },
            "SenderRole": {"v": "A08"},
            "ReceiverIdentification": {"v": " ", "codingScheme": "A01"},
            "ReceiverRole": {"v": "A05"},
            "CreationDateTime": {
                "v": datetime.now(timezone.utc)
                .replace(microsecond=0)
                .strftime("%Y-%m-%dT%H:%M:%SZ")
            },
            "RequestComponent": rc_list,
        }
        return self.client.service.GetData(request=request)

    def get_px_market_trades(
        self,
        start_time_utc: datetime,
        end_time_utc: datetime,
        time_resolution: str,
        px_trader: Optional[str] = None,
        px_trader_scheme: str = "A01",
        process_type: Optional[str] = None,
        mba: Optional[str] = None,
    ) -> Any:
        """
        Fetch **Power Exchange Market Trades (PXT)** data for exchange trading activities.

        Retrieves information about trades executed on power exchanges, including
        trade volumes, prices, and market participant details.

        Args:
            start_time_utc: Start time in UTC (tz-aware datetime).
            end_time_utc: End time in UTC (tz-aware datetime).
            time_resolution: ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.
            px_trader: Optional power exchange trader identifier.
            px_trader_scheme: Coding scheme for trader identifier (default `"A01"`).
            process_type: Optional process type filter for trade categorization.
            mba: Optional Metering Balance Area identifier.

        Returns:
            SOAP response object containing power exchange market trades data.

        Raises:
            Exception: If SOAP service call fails.
            ValueError: If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

        Example:
            ```python
            from datetime import datetime, timezone
            api = SoapApiClient(area="FI")
            result = api.get_px_market_trades(
                start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
                end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
                time_resolution="PT1H",
            px_trader="TRADER_123",
            process_type="A01"
            )
            ```
        """
        # Validate input parameters
        self._validate_datetime_parameters(start_time_utc, end_time_utc)
        self._validate_time_resolution(time_resolution)
        sender_coding = self.coding_scheme[self.area]
        sender_id = self.sender_indentification[self.area]
        rc_list = [
            {
                "RequestedAttribute": {"v": "DataFlow"},
                "RequestedAttributeValue": {"v": "PXT"},
            },
            {
                "RequestedAttribute": {"v": "TimeInterval"},
                "RequestedAttributeValue": {
                    "v": f"{start_time_utc.isoformat()}Z/{end_time_utc.isoformat()}Z"
                },
            },
            {
                "RequestedAttribute": {"v": "TimeResolution"},
                "RequestedAttributeValue": {"v": f"{time_resolution}"},
            },
        ]
        if px_trader:
            rc_list.append(
                {
                    "RequestedAttribute": {"v": "PXTrader"},
                    "RequestedAttributeValue": {
                        "v": f"{px_trader}",
                        "codingScheme": f"{px_trader_scheme}",
                    },
                }
            )
        if process_type:
            rc_list.append(
                {
                    "RequestedAttribute": {"v": "ProcessType"},
                    "RequestedAttributeValue": {"v": f"{process_type}"},
                }
            )
        if mba:
            rc_list.append(
                {
                    "RequestedAttribute": {"v": "MBA"},
                    "RequestedAttributeValue": {"v": f"{mba}", "codingScheme": "A01"},
                }
            )

        request = {
            "DocumentIdentification": {"v": "1"},
            "DocumentType": {"v": "A25"},
            "SenderIdentification": {
                "v": f"{sender_id}",
                "codingScheme": f"{sender_coding}",
            },
            "SenderRole": {"v": "A08"},
            "ReceiverIdentification": {"v": " ", "codingScheme": "A01"},
            "ReceiverRole": {"v": "A05"},
            "CreationDateTime": {
                "v": datetime.now(timezone.utc)
                .replace(microsecond=0)
                .strftime("%Y-%m-%dT%H:%M:%SZ")
            },
            "RequestComponent": rc_list,
        }
        return self.client.service.GetData(request=request)

    def get_px_market_flows(
        self,
        start_time_utc: datetime,
        end_time_utc: datetime,
        time_resolution: str,
        in_area: Optional[str] = None,
        out_area: Optional[str] = None,
        process_type: Optional[str] = None,
    ) -> Any:
        """
        Fetch **Power Exchange Market Flows (PXF)** data for cross-border electricity flows.

        Retrieves information about electricity flows between areas traded on power
        exchanges, including import/export volumes and flow directions.

        Args:
            start_time_utc: Start time in UTC (tz-aware datetime).
            end_time_utc: End time in UTC (tz-aware datetime).
            time_resolution: ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.
            in_area: Optional source area for import flows.
            out_area: Optional destination area for export flows.
            process_type: Optional process type filter for flow categorization.

        Returns:
            SOAP response object containing power exchange market flows data.

        Raises:
            Exception: If SOAP service call fails.
            ValueError: If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

        Example:
            ```python
            from datetime import datetime, timezone
            api = SoapApiClient(area="FI")
            result = api.get_px_market_flows(
                start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
                end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
                time_resolution="PT1H",
            in_,
            out_
            )
            ```
        """
        # Validate input parameters
        self._validate_datetime_parameters(start_time_utc, end_time_utc)
        self._validate_time_resolution(time_resolution)
        sender_coding = self.coding_scheme[self.area]
        sender_id = self.sender_indentification[self.area]
        rc_list = [
            {
                "RequestedAttribute": {"v": "DataFlow"},
                "RequestedAttributeValue": {"v": "PXF"},
            },
            {
                "RequestedAttribute": {"v": "TimeInterval"},
                "RequestedAttributeValue": {
                    "v": f"{start_time_utc.isoformat()}Z/{end_time_utc.isoformat()}Z"
                },
            },
            {
                "RequestedAttribute": {"v": "TimeResolution"},
                "RequestedAttributeValue": {"v": f"{time_resolution}"},
            },
        ]
        if in_area:
            rc_list.append(
                {
                    "RequestedAttribute": {"v": "InArea"},
                    "RequestedAttributeValue": {
                        "v": f"{in_area}",
                        "codingScheme": "A01",
                    },
                }
            )
        if out_area:
            rc_list.append(
                {
                    "RequestedAttribute": {"v": "OutArea"},
                    "RequestedAttributeValue": {
                        "v": f"{out_area}",
                        "codingScheme": "A01",
                    },
                }
            )
        if process_type:
            rc_list.append(
                {
                    "RequestedAttribute": {"v": "ProcessType"},
                    "RequestedAttributeValue": {"v": f"{process_type}"},
                }
            )

        request = {
            "DocumentIdentification": {"v": "1"},
            "DocumentType": {"v": "A25"},
            "SenderIdentification": {
                "v": f"{sender_id}",
                "codingScheme": f"{sender_coding}",
            },
            "SenderRole": {"v": "A08"},
            "ReceiverIdentification": {"v": " ", "codingScheme": "A01"},
            "ReceiverRole": {"v": "A05"},
            "CreationDateTime": {
                "v": datetime.now(timezone.utc)
                .replace(microsecond=0)
                .strftime("%Y-%m-%dT%H:%M:%SZ")
            },
            "RequestComponent": rc_list,
        }
        return self.client.service.GetData(request=request)

    def get_mga_exchanges(
        self,
        start_time_utc: datetime,
        end_time_utc: datetime,
        time_resolution: str,
        in_mga: Optional[str] = None,
        out_mga: Optional[str] = None,
    ) -> Any:
        """
        Fetch **Metering Grid Area (MGA) Exchanges (MGX)** data for inter-area electricity transfers.

        Retrieves information about electricity exchanges between different metering
        grid areas, including transfer volumes and settlement data.

        Args:
            start_time_utc: Start time in UTC (tz-aware datetime).
            end_time_utc: End time in UTC (tz-aware datetime).
            time_resolution: ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.
            in_mga: Optional source Metering Grid Area identifier.
            out_mga: Optional destination Metering Grid Area identifier.

        Returns:
            SOAP response object containing MGA exchanges data.

        Raises:
            Exception: If SOAP service call fails.
            ValueError: If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

        Example:
            ```python
            from datetime import datetime, timezone
            api = SoapApiClient(area="FI")
            result = api.get_mga_exchanges(
                start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
                end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
                time_resolution="PT1H",
            in_mga="FI_MGA_001",
            out_mga="FI_MGA_002"
            )
            ```
        """
        # Validate input parameters
        self._validate_datetime_parameters(start_time_utc, end_time_utc)
        self._validate_time_resolution(time_resolution)
        sender_coding = self.coding_scheme[self.area]
        sender_id = self.sender_indentification[self.area]
        rc_list = [
            {
                "RequestedAttribute": {"v": "DataFlow"},
                "RequestedAttributeValue": {"v": "MGX"},
            },
            {
                "RequestedAttribute": {"v": "TimeInterval"},
                "RequestedAttributeValue": {
                    "v": f"{start_time_utc.isoformat()}Z/{end_time_utc.isoformat()}Z"
                },
            },
            {
                "RequestedAttribute": {"v": "TimeResolution"},
                "RequestedAttributeValue": {"v": f"{time_resolution}"},
            },
        ]
        if in_mga:
            rc_list.append(
                {
                    "RequestedAttribute": {"v": "InMGA"},
                    "RequestedAttributeValue": {
                        "v": f"{in_mga}",
                        "codingScheme": "A01",
                    },
                }
            )
        if out_mga:
            rc_list.append(
                {
                    "RequestedAttribute": {"v": "OutMGA"},
                    "RequestedAttributeValue": {
                        "v": f"{out_mga}",
                        "codingScheme": "A01",
                    },
                }
            )

        request = {
            "DocumentIdentification": {"v": "1"},
            "DocumentType": {"v": "A25"},
            "SenderIdentification": {
                "v": f"{sender_id}",
                "codingScheme": f"{sender_coding}",
            },
            "SenderRole": {"v": "A08"},
            "ReceiverIdentification": {"v": " ", "codingScheme": "A01"},
            "ReceiverRole": {"v": "A05"},
            "CreationDateTime": {
                "v": datetime.now(timezone.utc)
                .replace(microsecond=0)
                .strftime("%Y-%m-%dT%H:%M:%SZ")
            },
            "RequestComponent": rc_list,
        }
        return self.client.service.GetData(request=request)

    def get_mga_exchange_trades(
        self,
        start_time_utc: datetime,
        end_time_utc: datetime,
        time_resolution: str,
        in_re: Optional[str] = None,
        out_re: Optional[str] = None,
        re_scheme: str = "A12",
        in_mga: Optional[str] = None,
        out_mga: Optional[str] = None,
    ) -> Any:
        """
        Fetch **MGA Exchange Trades (MGT)** data for trades between responsible entities and grid areas.

        Retrieves information about electricity trades between responsible entities
        across different metering grid areas, including trade volumes and pricing.

        Args:
            start_time_utc: Start time in UTC (tz-aware datetime).
            end_time_utc: End time in UTC (tz-aware datetime).
            time_resolution: ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.
            in_re: Optional incoming responsible entity identifier.
            out_re: Optional outgoing responsible entity identifier.
            re_scheme: Coding scheme for responsible entity IDs (default `"A12"`).
            in_mga: Optional source Metering Grid Area identifier.
            out_mga: Optional destination Metering Grid Area identifier.

        Returns:
            SOAP response object containing MGA exchange trades data.

        Raises:
            Exception: If SOAP service call fails.
            ValueError: If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

        Example:
            ```python
            from datetime import datetime, timezone
            api = SoapApiClient(area="FI")
            result = api.get_mga_exchange_trades(
                start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
                end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
                time_resolution="PT1H",
            in_re="RE_001",
            out_re="RE_002",
            in_mga="SE_MGA_001"
            )
            ```
        """
        # Validate input parameters
        self._validate_datetime_parameters(start_time_utc, end_time_utc)
        self._validate_time_resolution(time_resolution)
        sender_coding = self.coding_scheme[self.area]
        sender_id = self.sender_indentification[self.area]
        rc_list = [
            {
                "RequestedAttribute": {"v": "DataFlow"},
                "RequestedAttributeValue": {"v": "MGT"},
            },
            {
                "RequestedAttribute": {"v": "TimeInterval"},
                "RequestedAttributeValue": {
                    "v": f"{start_time_utc.isoformat()}Z/{end_time_utc.isoformat()}Z"
                },
            },
            {
                "RequestedAttribute": {"v": "TimeResolution"},
                "RequestedAttributeValue": {"v": f"{time_resolution}"},
            },
        ]
        if in_re:
            rc_list.append(
                {
                    "RequestedAttribute": {"v": "InRE"},
                    "RequestedAttributeValue": {
                        "v": f"{in_re}",
                        "codingScheme": f"{re_scheme}",
                    },
                }
            )
        if out_re:
            rc_list.append(
                {
                    "RequestedAttribute": {"v": "OutRE"},
                    "RequestedAttributeValue": {
                        "v": f"{out_re}",
                        "codingScheme": f"{re_scheme}",
                    },
                }
            )
        if in_mga:
            rc_list.append(
                {
                    "RequestedAttribute": {"v": "InMGA"},
                    "RequestedAttributeValue": {
                        "v": f"{in_mga}",
                        "codingScheme": "A01",
                    },
                }
            )
        if out_mga:
            rc_list.append(
                {
                    "RequestedAttribute": {"v": "OutMGA"},
                    "RequestedAttributeValue": {
                        "v": f"{out_mga}",
                        "codingScheme": "A01",
                    },
                }
            )

        request = {
            "DocumentIdentification": {"v": "1"},
            "DocumentType": {"v": "A25"},
            "SenderIdentification": {
                "v": f"{sender_id}",
                "codingScheme": f"{sender_coding}",
            },
            "SenderRole": {"v": "A08"},
            "ReceiverIdentification": {"v": " ", "codingScheme": "A01"},
            "ReceiverRole": {"v": "A05"},
            "CreationDateTime": {
                "v": datetime.now(timezone.utc)
                .replace(microsecond=0)
                .strftime("%Y-%m-%dT%H:%M:%SZ")
            },
            "RequestComponent": rc_list,
        }
        return self.client.service.GetData(request=request)

    def get_consumption(
        self,
        start_time_utc: datetime,
        end_time_utc: datetime,
        time_resolution: str,
        mba: Optional[str] = None,
    ) -> Any:
        """
        Fetch **Consumption (REC)** data for electricity consumption by area.

        Retrieves measured electricity consumption data used for settlement calculations
        and grid balancing. Data represents actual consumption by end users.

        Args:
            start_time_utc: Start time in UTC (tz-aware datetime).
            end_time_utc: End time in UTC (tz-aware datetime).
            time_resolution: ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.
            mba: Optional Metering Grid Area identifier for filtering.

        Returns:
            SOAP response object containing consumption data.

        Raises:
            Exception: If SOAP service call fails.
            ValueError: If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

        Example:
            ```python
            from datetime import datetime, timezone
            api = SoapApiClient(area="FI")
            result = api.get_consumption(
                start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
                end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
                time_resolution="PT1H",
                mba="FI_MGA_001"
            )
            ```
        """
        # Validate input parameters
        self._validate_datetime_parameters(start_time_utc, end_time_utc)
        self._validate_time_resolution(time_resolution)
        sender_coding = self.coding_scheme[self.area]
        sender_id = self.sender_indentification[self.area]
        rc_list = [
            {
                "RequestedAttribute": {"v": "DataFlow"},
                "RequestedAttributeValue": {"v": "REC"},
            },
            {
                "RequestedAttribute": {"v": "TimeInterval"},
                "RequestedAttributeValue": {
                    "v": f"{start_time_utc.isoformat()}Z/{end_time_utc.isoformat()}Z"
                },
            },
            {
                "RequestedAttribute": {"v": "TimeResolution"},
                "RequestedAttributeValue": {"v": f"{time_resolution}"},
            },
        ]
        if mba:
            rc_list.append(
                {
                    "RequestedAttribute": {"v": "MGA"},
                    "RequestedAttributeValue": {"v": f"{mba}", "codingScheme": "A01"},
                }
            )
        request = {
            "DocumentIdentification": {"v": "1"},
            "DocumentType": {"v": "A25"},
            "SenderIdentification": {
                "v": f"{sender_id}",
                "codingScheme": f"{sender_coding}",
            },
            "SenderRole": {"v": "A08"},
            "ReceiverIdentification": {"v": " ", "codingScheme": "A01"},
            "ReceiverRole": {"v": "A05"},
            "CreationDateTime": {
                "v": datetime.now(timezone.utc)
                .replace(microsecond=0)
                .strftime("%Y-%m-%dT%H:%M:%SZ")
            },
            "RequestComponent": rc_list,
        }
        return self.client.service.GetData(request=request)

    def get_production(
        self,
        start_time_utc: datetime,
        end_time_utc: datetime,
        time_resolution: str,
        mba: Optional[str] = None,
    ) -> Any:
        """
        Fetch **Production (RPM)** data for electricity generation by area.

        Retrieves measured electricity production data from generation units, used for
        settlement calculations and grid balancing. Data represents actual generation output.

        Args:
            start_time_utc: Start time in UTC (tz-aware datetime).
            end_time_utc: End time in UTC (tz-aware datetime).
            time_resolution: ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.
            mba: Optional Metering Grid Area identifier for filtering.

        Returns:
            SOAP response object containing production data.

        Raises:
            Exception: If SOAP service call fails.
            ValueError: If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

        Example:
            ```python
            from datetime import datetime, timezone
            api = SoapApiClient(area="FI")
            result = api.get_production(
                start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
                end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
                time_resolution="PT1H",
                mba="SE_MGA_001"
            )
            ```
        """
        # Validate input parameters
        self._validate_datetime_parameters(start_time_utc, end_time_utc)
        self._validate_time_resolution(time_resolution)
        sender_coding = self.coding_scheme[self.area]
        sender_id = self.sender_indentification[self.area]
        rc_list = [
            {
                "RequestedAttribute": {"v": "DataFlow"},
                "RequestedAttributeValue": {"v": "RPM"},
            },
            {
                "RequestedAttribute": {"v": "TimeInterval"},
                "RequestedAttributeValue": {
                    "v": f"{start_time_utc.isoformat()}Z/{end_time_utc.isoformat()}Z"
                },
            },
            {
                "RequestedAttribute": {"v": "TimeResolution"},
                "RequestedAttributeValue": {"v": f"{time_resolution}"},
            },
        ]
        if mba:
            rc_list.append(
                {
                    "RequestedAttribute": {"v": "MGA"},
                    "RequestedAttributeValue": {"v": f"{mba}", "codingScheme": "A01"},
                }
            )
        request = {
            "DocumentIdentification": {"v": "1"},
            "DocumentType": {"v": "A25"},
            "SenderIdentification": {
                "v": f"{sender_id}",
                "codingScheme": f"{sender_coding}",
            },
            "SenderRole": {"v": "A08"},
            "ReceiverIdentification": {"v": " ", "codingScheme": "A01"},
            "ReceiverRole": {"v": "A05"},
            "CreationDateTime": {
                "v": datetime.now(timezone.utc)
                .replace(microsecond=0)
                .strftime("%Y-%m-%dT%H:%M:%SZ")
            },
            "RequestComponent": rc_list,
        }
        return self.client.service.GetData(request=request)

    def get_production_plan(
        self,
        start_time_utc: datetime,
        end_time_utc: datetime,
        time_resolution: str,
    ) -> Any:
        """
        Fetch **Production Plan (PRP)** data for planned electricity generation.

        Retrieves planned production schedules submitted by generators, used for
        comparing against actual production and calculating imbalances.

        Args:
            start_time_utc: Start time in UTC (tz-aware datetime).
            end_time_utc: End time in UTC (tz-aware datetime).
            time_resolution: ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.

        Returns:
            SOAP response object containing production plan data.

        Raises:
            Exception: If SOAP service call fails.
            ValueError: If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

        Example:
            ```python
            from datetime import datetime, timezone
            api = SoapApiClient(area="FI")
            result = api.get_production_plan(
                start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
                end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
                time_resolution="PT1H",

            )
            ```
        """
        # Validate input parameters
        self._validate_datetime_parameters(start_time_utc, end_time_utc)
        self._validate_time_resolution(time_resolution)
        sender_coding = self.coding_scheme[self.area]
        sender_id = self.sender_indentification[self.area]
        request = {
            "DocumentIdentification": {"v": "1"},
            "DocumentType": {"v": "A25"},
            "SenderIdentification": {
                "v": f"{sender_id}",
                "codingScheme": f"{sender_coding}",
            },
            "SenderRole": {"v": "A08"},
            "ReceiverIdentification": {"v": " ", "codingScheme": "A01"},
            "ReceiverRole": {"v": "A05"},
            "CreationDateTime": {
                "v": datetime.now(timezone.utc)
                .replace(microsecond=0)
                .strftime("%Y-%m-%dT%H:%M:%SZ")
            },
            "RequestComponent": [
                {
                    "RequestedAttribute": {"v": "DataFlow"},
                    "RequestedAttributeValue": {"v": "PRP"},
                },
                {
                    "RequestedAttribute": {"v": "TimeInterval"},
                    "RequestedAttributeValue": {
                        "v": f"{start_time_utc.isoformat()}Z/{end_time_utc.isoformat()}Z"
                    },
                },
                {
                    "RequestedAttribute": {"v": "TimeResolution"},
                    "RequestedAttributeValue": {"v": f"{time_resolution}"},
                },
            ],
        }
        return self.client.service.GetData(request=request)

    def get_prices(
        self,
        start_time_utc: datetime,
        end_time_utc: datetime,
        time_resolution: str,
    ) -> Any:
        """
        Fetch **Prices (REP)** - settlement prices for electricity trading.

        Retrieves official settlement prices used for imbalance settlement and financial
        settlement of electricity trades in the Nordic market.

        Args:
            start_time_utc: Start time in UTC (tz-aware datetime).
            end_time_utc: End time in UTC (tz-aware datetime).
            time_resolution: ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.

        Returns:
            SOAP response object containing settlement price data.

        Raises:
            Exception: If SOAP service call fails.
            ValueError: If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

        Example:
            ```python
            from datetime import datetime, timezone
            api = SoapApiClient(area="FI")
            result = api.get_prices(
                start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
                end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
                time_resolution="PT1H",

            )
            ```
        """
        # Validate input parameters
        self._validate_datetime_parameters(start_time_utc, end_time_utc)
        self._validate_time_resolution(time_resolution)
        sender_coding = self.coding_scheme[self.area]
        sender_id = self.sender_indentification[self.area]
        request = {
            "DocumentIdentification": {"v": "1"},
            "DocumentType": {"v": "A25"},
            "SenderIdentification": {
                "v": f"{sender_id}",
                "codingScheme": f"{sender_coding}",
            },
            "SenderRole": {"v": "A08"},
            "ReceiverIdentification": {"v": " ", "codingScheme": "A01"},
            "ReceiverRole": {"v": "A05"},
            "CreationDateTime": {
                "v": datetime.now(timezone.utc)
                .replace(microsecond=0)
                .strftime("%Y-%m-%dT%H:%M:%SZ")
            },
            "RequestComponent": [
                {
                    "RequestedAttribute": {"v": "DataFlow"},
                    "RequestedAttributeValue": {"v": "REP"},
                },
                {
                    "RequestedAttribute": {"v": "TimeInterval"},
                    "RequestedAttributeValue": {
                        "v": f"{start_time_utc.isoformat()}Z/{end_time_utc.isoformat()}Z"
                    },
                },
                {
                    "RequestedAttribute": {"v": "TimeResolution"},
                    "RequestedAttributeValue": {"v": f"{time_resolution}"},
                },
            ],
        }
        return self.client.service.GetData(request=request)

    def get_consumption_imbalance(
        self,
        start_time_utc: datetime,
        end_time_utc: datetime,
        time_resolution: str,
    ) -> Any:
        """
        Fetch **Consumption Imbalance (CIM)** data for consumption forecast deviations.

        Retrieves information about imbalances between forecasted and actual electricity
        consumption, used for settlement calculations and grid balancing.

        Args:
            start_time_utc: Start time in UTC (tz-aware datetime).
            end_time_utc: End time in UTC (tz-aware datetime).
            time_resolution: ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.

        Returns:
            SOAP response object containing consumption imbalance data.

        Raises:
            Exception: If SOAP service call fails.
            ValueError: If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

        Example:
            ```python
            from datetime import datetime, timezone
            api = SoapApiClient(area="FI")
            result = api.get_consumption_imbalance(
                start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
                end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
                time_resolution="PT15M",

            )
            ```
        """
        # Validate input parameters
        self._validate_datetime_parameters(start_time_utc, end_time_utc)
        self._validate_time_resolution(time_resolution)
        sender_coding = self.coding_scheme[self.area]
        sender_id = self.sender_indentification[self.area]
        request = {
            "DocumentIdentification": {"v": "1"},
            "DocumentType": {"v": "A25"},
            "SenderIdentification": {
                "v": f"{sender_id}",
                "codingScheme": f"{sender_coding}",
            },
            "SenderRole": {"v": "A08"},
            "ReceiverIdentification": {"v": " ", "codingScheme": "A01"},
            "ReceiverRole": {"v": "A05"},
            "CreationDateTime": {
                "v": datetime.now(timezone.utc)
                .replace(microsecond=0)
                .strftime("%Y-%m-%dT%H:%M:%SZ")
            },
            "RequestComponent": [
                {
                    "RequestedAttribute": {"v": "DataFlow"},
                    "RequestedAttributeValue": {"v": "CIM"},
                },
                {
                    "RequestedAttribute": {"v": "TimeInterval"},
                    "RequestedAttributeValue": {
                        "v": f"{start_time_utc.isoformat()}Z/{end_time_utc.isoformat()}Z"
                    },
                },
                {
                    "RequestedAttribute": {"v": "TimeResolution"},
                    "RequestedAttributeValue": {"v": f"{time_resolution}"},
                },
            ],
        }
        return self.client.service.GetData(request=request)

    def get_production_imbalance(
        self,
        start_time_utc: datetime,
        end_time_utc: datetime,
        time_resolution: str,
    ) -> Any:
        """
        Fetch **Production Imbalance (PIM)** data for production forecast deviations.

        Retrieves information about imbalances between forecasted and actual electricity
        production, used for settlement calculations and grid balancing.

        Args:
            start_time_utc: Start time in UTC (tz-aware datetime).
            end_time_utc: End time in UTC (tz-aware datetime).
            time_resolution: ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.

        Returns:
            SOAP response object containing production imbalance data.

        Raises:
            Exception: If SOAP service call fails.
            ValueError: If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

        Example:
            ```python
            from datetime import datetime, timezone
            api = SoapApiClient(area="FI")
            result = api.get_production_imbalance(
                start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
                end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
                time_resolution="PT15M",

            )
            ```
        """
        # Validate input parameters
        self._validate_datetime_parameters(start_time_utc, end_time_utc)
        self._validate_time_resolution(time_resolution)
        sender_coding = self.coding_scheme[self.area]
        sender_id = self.sender_indentification[self.area]
        request = {
            "DocumentIdentification": {"v": "1"},
            "DocumentType": {"v": "A25"},
            "SenderIdentification": {
                "v": f"{sender_id}",
                "codingScheme": f"{sender_coding}",
            },
            "SenderRole": {"v": "A08"},
            "ReceiverIdentification": {"v": " ", "codingScheme": "A01"},
            "ReceiverRole": {"v": "A05"},
            "CreationDateTime": {
                "v": datetime.now(timezone.utc)
                .replace(microsecond=0)
                .strftime("%Y-%m-%dT%H:%M:%SZ")
            },
            "RequestComponent": [
                {
                    "RequestedAttribute": {"v": "DataFlow"},
                    "RequestedAttributeValue": {"v": "PIM"},
                },
                {
                    "RequestedAttribute": {"v": "TimeInterval"},
                    "RequestedAttributeValue": {
                        "v": f"{start_time_utc.isoformat()}Z/{end_time_utc.isoformat()}Z"
                    },
                },
                {
                    "RequestedAttribute": {"v": "TimeResolution"},
                    "RequestedAttributeValue": {"v": f"{time_resolution}"},
                },
            ],
        }
        return self.client.service.GetData(request=request)

    def get_imbalance(
        self,
        start_time_utc: datetime,
        end_time_utc: datetime,
        time_resolution: str,
    ) -> Any:
        """
        Fetch **Imbalance (IM)** data for system-wide balance deviations.

        Retrieves comprehensive imbalance data showing the difference between planned
        and actual electricity supply/demand, used for settlement and grid management.

        Args:
            start_time_utc: Start time in UTC (tz-aware datetime).
            end_time_utc: End time in UTC (tz-aware datetime).
            time_resolution: ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.

        Returns:
            SOAP response object containing imbalance data.

        Raises:
            Exception: If SOAP service call fails.
            ValueError: If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

        Example:
            ```python
            from datetime import datetime, timezone
            api = SoapApiClient(area="FI")
            result = api.get_imbalance(
                start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
                end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
                time_resolution="PT15M",

            )
            ```
        """
        # Validate input parameters
        self._validate_datetime_parameters(start_time_utc, end_time_utc)
        self._validate_time_resolution(time_resolution)

        sender_coding = self.coding_scheme[self.area]
        sender_id = self.sender_indentification[self.area]
        request = {
            "DocumentIdentification": {"v": "1"},
            "DocumentType": {"v": "A25"},
            "SenderIdentification": {
                "v": f"{sender_id}",
                "codingScheme": f"{sender_coding}",
            },
            "SenderRole": {"v": "A08"},
            "ReceiverIdentification": {"v": " ", "codingScheme": "A01"},
            "ReceiverRole": {"v": "A05"},
            "CreationDateTime": {
                "v": datetime.now(timezone.utc)
                .replace(microsecond=0)
                .strftime("%Y-%m-%dT%H:%M:%SZ")
            },
            "RequestComponent": [
                {
                    "RequestedAttribute": {"v": "DataFlow"},
                    "RequestedAttributeValue": {"v": "IM"},
                },
                {
                    "RequestedAttribute": {"v": "TimeInterval"},
                    "RequestedAttributeValue": {
                        "v": f"{start_time_utc.isoformat()}Z/{end_time_utc.isoformat()}Z"
                    },
                },
                {
                    "RequestedAttribute": {"v": "TimeResolution"},
                    "RequestedAttributeValue": {"v": f"{time_resolution}"},
                },
            ],
        }
        return self.client.service.GetData(request=request)

    def get_mga_imbalance(
        self,
        start_time_utc: datetime,
        end_time_utc: datetime,
        time_resolution: str,
    ) -> Any:
        """
        Fetch **Metering Grid Area Imbalance (MIM)** data for grid area balance deviations.

        Retrieves information about imbalances within specific metering grid areas,
        representing the difference between planned and actual energy flows.

        Args:
            start_time_utc: Start time in UTC (tz-aware datetime).
            end_time_utc: End time in UTC (tz-aware datetime).
            time_resolution: ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.

        Returns:
            SOAP response object containing MGA imbalance data.

        Raises:
            Exception: If SOAP service call fails.
            ValueError: If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

        Example:
            ```python
            from datetime import datetime, timezone
            api = SoapApiClient(area="FI")
            result = api.get_mga_imbalance(
                start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
                end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
                time_resolution="PT1H",

            )
            ```
        """
        # Validate input parameters
        self._validate_datetime_parameters(start_time_utc, end_time_utc)
        self._validate_time_resolution(time_resolution)
        sender_coding = self.coding_scheme[self.area]
        sender_id = self.sender_indentification[self.area]
        request = {
            "DocumentIdentification": {"v": "1"},
            "DocumentType": {"v": "A25"},
            "SenderIdentification": {
                "v": f"{sender_id}",
                "codingScheme": f"{sender_coding}",
            },
            "SenderRole": {"v": "A08"},
            "ReceiverIdentification": {"v": " ", "codingScheme": "A01"},
            "ReceiverRole": {"v": "A05"},
            "CreationDateTime": {
                "v": datetime.now(timezone.utc)
                .replace(microsecond=0)
                .strftime("%Y-%m-%dT%H:%M:%SZ")
            },
            "RequestComponent": [
                {
                    "RequestedAttribute": {"v": "DataFlow"},
                    "RequestedAttributeValue": {"v": "MIM"},
                },
                {
                    "RequestedAttribute": {"v": "TimeInterval"},
                    "RequestedAttributeValue": {
                        "v": f"{start_time_utc.isoformat()}Z/{end_time_utc.isoformat()}Z"
                    },
                },
                {
                    "RequestedAttribute": {"v": "TimeResolution"},
                    "RequestedAttributeValue": {"v": f"{time_resolution}"},
                },
            ],
        }
        return self.client.service.GetData(request=request)

    def get_mga_mba_relations(
        self,
        start_time_utc: datetime,
        end_time_utc: datetime,
        time_resolution: str,
        sender_role: str = "A18",
    ) -> Any:
        """
        Fetch **MGA-MBA Relations (ARE)** data for grid area relationship mappings.

        Retrieves information about relationships between Metering Grid Areas (MGA)
        and Metering Balance Areas (MBA), used for settlement and grid topology.

        Args:
            start_time_utc: Start time in UTC (tz-aware datetime).
            end_time_utc: End time in UTC (tz-aware datetime).
            time_resolution: ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.
            sender_role: Sender role code (default `"A18"` for DSO/Datahub/TSO).

        Returns:
            SOAP response object containing MGA-MBA relations data.

        Raises:
            Exception: If SOAP service call fails.
            ValueError: If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

        Example:
            ```python
            from datetime import datetime, timezone
            api = SoapApiClient(area="FI")
            result = api.get_mga_mba_relations(
                start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
                end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
                time_resolution="P1D",
            ,
                sender_role="A18"
            )
            ```
        """
        # Validate input parameters
        self._validate_datetime_parameters(start_time_utc, end_time_utc)
        self._validate_time_resolution(time_resolution)
        sender_coding = self.coding_scheme[self.area]
        sender_id = self.sender_indentification[self.area]
        request = {
            "DocumentIdentification": {"v": "1"},
            "DocumentType": {"v": "A25"},
            "SenderIdentification": {
                "v": f"{sender_id}",
                "codingScheme": f"{sender_coding}",
            },
            "SenderRole": {"v": f"{sender_role}"},
            "ReceiverIdentification": {"v": " ", "codingScheme": "A01"},
            "ReceiverRole": {"v": "A05"},
            "CreationDateTime": {
                "v": datetime.now(timezone.utc)
                .replace(microsecond=0)
                .strftime("%Y-%m-%dT%H:%M:%SZ")
            },
            "RequestComponent": [
                {
                    "RequestedAttribute": {"v": "DataFlow"},
                    "RequestedAttributeValue": {"v": "ARE"},
                },
                {
                    "RequestedAttribute": {"v": "TimeInterval"},
                    "RequestedAttributeValue": {
                        "v": f"{start_time_utc.isoformat()}Z/{end_time_utc.isoformat()}Z"
                    },
                },
                {
                    "RequestedAttribute": {"v": "TimeResolution"},
                    "RequestedAttributeValue": {"v": f"{time_resolution}"},
                },
            ],
        }
        return self.client.service.GetData(request=request)

    def get_production_per_unit_type_mga(
        self,
        start_time_utc: datetime,
        end_time_utc: datetime,
        time_resolution: str,
    ) -> Any:
        """
        Fetch **Production per Unit Type and MGA (PROD_MGA_PUT)** data for categorized production.

        Retrieves production data categorized by production unit types within specific
        Metering Grid Areas, used for renewable energy tracking and settlement.

        Args:
            start_time_utc: Start time in UTC (tz-aware datetime).
            end_time_utc: End time in UTC (tz-aware datetime).
            time_resolution: ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.

        Returns:
            SOAP response object containing production per unit type and MGA data.

        Raises:
            Exception: If SOAP service call fails.
            ValueError: If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

        Example:
            ```python
            from datetime import datetime, timezone
            api = SoapApiClient(area="FI")
            result = api.get_production_per_unit_type_mga(
                start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
                end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
                time_resolution="PT1H",

            )
            ```
        """
        # Validate input parameters
        self._validate_datetime_parameters(start_time_utc, end_time_utc)
        self._validate_time_resolution(time_resolution)
        sender_coding = self.coding_scheme[self.area]
        sender_id = self.sender_indentification[self.area]
        request = {
            "DocumentIdentification": {"v": "1"},
            "DocumentType": {"v": "A25"},
            "SenderIdentification": {
                "v": f"{sender_id}",
                "codingScheme": f"{sender_coding}",
            },
            "SenderRole": {"v": "A08"},
            "ReceiverIdentification": {"v": " ", "codingScheme": "A01"},
            "ReceiverRole": {"v": "A05"},
            "CreationDateTime": {
                "v": datetime.now(timezone.utc)
                .replace(microsecond=0)
                .strftime("%Y-%m-%dT%H:%M:%SZ")
            },
            "RequestComponent": [
                {
                    "RequestedAttribute": {"v": "DataFlow"},
                    "RequestedAttributeValue": {"v": "PROD_MGA_PUT"},
                },
                {
                    "RequestedAttribute": {"v": "TimeInterval"},
                    "RequestedAttributeValue": {
                        "v": f"{start_time_utc.isoformat()}Z/{end_time_utc.isoformat()}Z"
                    },
                },
                {
                    "RequestedAttribute": {"v": "TimeResolution"},
                    "RequestedAttributeValue": {"v": f"{time_resolution}"},
                },
            ],
        }
        return self.client.service.GetData(request=request)

__init__(username=None, password=None, area=None)

Initialize the API client.

Parameters:

Name	Type	Description	Default
username	str	eSett account username. If None, read from keys file.	None
password	str	eSett account password or Azure Key Vault secret value. If None, read from keys file.	None
area	str	Market area code (e.g., "SE", "FI", "NO").	None

Raises:

Type	Description
URLError	If token request fails.
KeyError	If required keys are missing from configuration.
ValueError	If area is not one of the supported market areas.

Example

from physical_operations_utils.esett_utils.eSettSoapApi import SoapApiClient
api = SoapApiClient(area="FI")  # pulls credentials from the keys file/Azure Key Vault

Source code in physical_operations_utils/esett_utils/eSettSoapApi.py

def __init__(
    self, username: str = None, password: str = None, area: str = None
) -> None:
    """
    Initialize the API client.

    Args:
        username: eSett account username. If `None`, read from keys file.
        password: eSett account password or Azure Key Vault secret value. If `None`, read from keys file.
        area: Market area code (e.g., `"SE"`, `"FI"`, `"NO"`).

    Raises:
        urllib.error.URLError: If token request fails.
        KeyError: If required keys are missing from configuration.
        ValueError: If area is not one of the supported market areas.

    Example:
        ```python
        from physical_operations_utils.esett_utils.eSettSoapApi import SoapApiClient
        api = SoapApiClient(area="FI")  # pulls credentials from the keys file/Azure Key Vault
        ```
    """
    # Validate area parameter
    if area is not None and area not in self.VALID_AREAS:
        raise ValueError(
            f"Invalid area '{area}'. Must be one of: {', '.join(sorted(self.VALID_AREAS))}"
        )

    self.coding_scheme = {
        "EIC": "A01",  # EIC
        "FI": "A10",  # GS1
        "SE": "NSE",  # National Sweden
        "NO": "A10",  # National Norway
        "DK": "NDK",  # National Denmark
    }

    self.sender_indentification = {
        "FI": "6430076111111",
        "SE": "14600",
        "NO": "7080005010788",
        "DK": "5790000000031",
    }

    self.credentials = {
        "SE": "eSett_SOAP_API_SE",
        "FI": "eSett_SOAP_API_FI",
        "NO": "eSett_SOAP_API_NO",
    }

    keys = get_keys_yaml_file().get(self.credentials[area])

    if username is None:
        username = keys["username"]
    if password is None:
        secret = keys["secret"]
        password = get_secret(secret)

    self.area = area

    self.wsdl_url = "https://service.esett.com/INFS/InformationService.svc?wsdl"

    self.client = Client(wsdl=self.wsdl_url, wsse=UsernameToken(username, password))

get_activated_reserves(start_time_utc, end_time_utc, time_resolution, business_type, reason_code, reason_code_2=None, regulation_object=None, mba=None)

Fetch Activated Reserves (ACR) data for frequency regulation and balancing services.

Retrieves information about reserves that were activated to maintain system balance, including both upward and downward regulation volumes and associated costs.

Parameters:

Name	Type	Description	Default
start_time_utc	datetime	Start time in UTC (tz-aware datetime).	required
end_time_utc	datetime	End time in UTC (tz-aware datetime).	required
time_resolution	str	ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.	required
business_type	str	Business type code (e.g., "A95" for frequency restoration).	required
reason_code	str	Primary reason code for activation (e.g., "A01").	required
reason_code_2	Optional[str]	Optional secondary reason code for activation.	None
regulation_object	Optional[str]	Optional specific regulation object identifier.	None
mba	Optional[str]	Optional Metering Balance Area identifier.	None

Returns:

Type	Description
Any	SOAP response object containing activated reserves data.

Raises:

Type	Description
Exception	If SOAP service call fails.
ValueError	If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

Example

from datetime import datetime, timezone
api = SoapApiClient(area="FI")
result = api.get_activated_reserves(
    start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
    end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
    time_resolution="PT1H",
    business_type="A95",
    reason_code="A01",
    reason_code_2="A02",
    mba="SE_MBA_001"
)

Source code in physical_operations_utils/esett_utils/eSettSoapApi.py

def get_activated_reserves(
    self,
    start_time_utc: datetime,
    end_time_utc: datetime,
    time_resolution: str,
    business_type: str,
    reason_code: str,
    reason_code_2: Optional[str] = None,
    regulation_object: Optional[str] = None,
    mba: Optional[str] = None,
) -> Any:
    """
    Fetch **Activated Reserves (ACR)** data for frequency regulation and balancing services.

    Retrieves information about reserves that were activated to maintain system balance,
    including both upward and downward regulation volumes and associated costs.

    Args:
        start_time_utc: Start time in UTC (tz-aware datetime).
        end_time_utc: End time in UTC (tz-aware datetime).
        time_resolution: ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.
        business_type: Business type code (e.g., `"A95"` for frequency restoration).
        reason_code: Primary reason code for activation (e.g., `"A01"`).
        reason_code_2: Optional secondary reason code for activation.
        regulation_object: Optional specific regulation object identifier.
        mba: Optional Metering Balance Area identifier.

    Returns:
        SOAP response object containing activated reserves data.

    Raises:
        Exception: If SOAP service call fails.
        ValueError: If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

    Example:
        ```python
        from datetime import datetime, timezone
        api = SoapApiClient(area="FI")
        result = api.get_activated_reserves(
            start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
            end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
            time_resolution="PT1H",
            business_type="A95",
            reason_code="A01",
            reason_code_2="A02",
            mba="SE_MBA_001"
        )
        ```
    """
    # Validate input parameters
    self._validate_datetime_parameters(start_time_utc, end_time_utc)
    self._validate_time_resolution(time_resolution)
    sender_coding = self.coding_scheme[self.area]
    sender_id = self.sender_indentification[self.area]
    rc_list = [
        {
            "RequestedAttribute": {"v": "DataFlow"},
            "RequestedAttributeValue": {"v": "ACR"},
        },
        {
            "RequestedAttribute": {"v": "TimeInterval"},
            "RequestedAttributeValue": {
                "v": f"{start_time_utc.isoformat()}Z/{end_time_utc.isoformat()}Z"
            },
        },
        {
            "RequestedAttribute": {"v": "TimeResolution"},
            "RequestedAttributeValue": {"v": f"{time_resolution}"},
        },
        {
            "RequestedAttribute": {"v": "BusinessType"},
            "RequestedAttributeValue": {"v": f"{business_type}"},
        },
        {
            "RequestedAttribute": {"v": "ReasonCode"},
            "RequestedAttributeValue": {"v": f"{reason_code}"},
        },
    ]
    if reason_code_2:
        rc_list.append(
            {
                "RequestedAttribute": {"v": "ReasonCode"},
                "RequestedAttributeValue": {"v": f"{reason_code_2}"},
            }
        )
    if regulation_object:
        rc_list.append(
            {
                "RequestedAttribute": {"v": "RegulationObject"},
                "RequestedAttributeValue": {
                    "v": f"{regulation_object}",
                    "codingScheme": f"{sender_coding}",
                },
            }
        )
    if mba:
        rc_list.append(
            {
                "RequestedAttribute": {"v": "MBA"},
                "RequestedAttributeValue": {"v": f"{mba}", "codingScheme": "A01"},
            }
        )

    request = {
        "DocumentIdentification": {"v": "1"},
        "DocumentType": {"v": "A25"},
        "SenderIdentification": {
            "v": f"{sender_id}",
            "codingScheme": f"{sender_coding}",
        },
        "SenderRole": {
            "v": "A08"
        },  # Use "A46" if you must act as BSP after BSP go-live window【60-22】
        "ReceiverIdentification": {"v": " ", "codingScheme": "A01"},
        "ReceiverRole": {"v": "A05"},
        "CreationDateTime": {
            "v": datetime.now(timezone.utc)
            .replace(microsecond=0)
            .strftime("%Y-%m-%dT%H:%M:%SZ")
        },
        "RequestComponent": rc_list,
    }
    return self.client.service.GetData(request=request)

get_bilateral_trades(start_time_utc, end_time_utc, time_resolution, in_brp=None, out_brp=None, agreement_id=None, mba=None, brp_scheme='A01')

Fetch Bilateral Trades (BIT) data for direct energy trading between parties.

Retrieves information about bilateral energy transactions between balance responsible parties, including trade volumes, prices, and settlement details.

Parameters:

Name	Type	Description	Default
start_time_utc	datetime	Start time in UTC (tz-aware datetime).	required
end_time_utc	datetime	End time in UTC (tz-aware datetime).	required
time_resolution	str	ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.	required
in_brp	Optional[str]	Optional incoming Balance Responsible Party identifier.	None
out_brp	Optional[str]	Optional outgoing Balance Responsible Party identifier.	None
agreement_id	Optional[str]	Optional bilateral agreement identifier.	None
mba	Optional[str]	Optional Metering Balance Area identifier.	None
brp_scheme	str	Coding scheme for BRP identifiers (default "A01").	'A01'

Returns:

Type	Description
Any	SOAP response object containing bilateral trades data.

Raises:

Type	Description
Exception	If SOAP service call fails.
ValueError	If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

Example

from datetime import datetime, timezone
api = SoapApiClient(area="FI")
result = api.get_bilateral_trades(
    start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
    end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
    time_resolution="PT1H",
in_brp="BRP_001",
out_brp="BRP_002",
agreement_id="BILATERAL_123"
)

Source code in physical_operations_utils/esett_utils/eSettSoapApi.py

def get_bilateral_trades(
    self,
    start_time_utc: datetime,
    end_time_utc: datetime,
    time_resolution: str,
    in_brp: Optional[str] = None,
    out_brp: Optional[str] = None,
    agreement_id: Optional[str] = None,
    mba: Optional[str] = None,
    brp_scheme: str = "A01",
) -> Any:
    """
    Fetch **Bilateral Trades (BIT)** data for direct energy trading between parties.

    Retrieves information about bilateral energy transactions between balance responsible
    parties, including trade volumes, prices, and settlement details.

    Args:
        start_time_utc: Start time in UTC (tz-aware datetime).
        end_time_utc: End time in UTC (tz-aware datetime).
        time_resolution: ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.
        in_brp: Optional incoming Balance Responsible Party identifier.
        out_brp: Optional outgoing Balance Responsible Party identifier.
        agreement_id: Optional bilateral agreement identifier.
        mba: Optional Metering Balance Area identifier.
        brp_scheme: Coding scheme for BRP identifiers (default `"A01"`).

    Returns:
        SOAP response object containing bilateral trades data.

    Raises:
        Exception: If SOAP service call fails.
        ValueError: If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

    Example:
        ```python
        from datetime import datetime, timezone
        api = SoapApiClient(area="FI")
        result = api.get_bilateral_trades(
            start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
            end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
            time_resolution="PT1H",
        in_brp="BRP_001",
        out_brp="BRP_002",
        agreement_id="BILATERAL_123"
        )
        ```
    """
    # Validate input parameters
    self._validate_datetime_parameters(start_time_utc, end_time_utc)
    self._validate_time_resolution(time_resolution)
    sender_coding = self.coding_scheme[self.area]
    sender_id = self.sender_indentification[self.area]
    rc_list = [
        {
            "RequestedAttribute": {"v": "DataFlow"},
            "RequestedAttributeValue": {"v": "BIT"},
        },
        {
            "RequestedAttribute": {"v": "TimeInterval"},
            "RequestedAttributeValue": {
                "v": f"{start_time_utc.isoformat()}Z/{end_time_utc.isoformat()}Z"
            },
        },
        {
            "RequestedAttribute": {"v": "TimeResolution"},
            "RequestedAttributeValue": {"v": f"{time_resolution}"},
        },
    ]
    if in_brp:
        rc_list.append(
            {
                "RequestedAttribute": {"v": "InBRP"},
                "RequestedAttributeValue": {
                    "v": f"{in_brp}",
                    "codingScheme": f"{brp_scheme}",
                },
            }
        )
    if out_brp:
        rc_list.append(
            {
                "RequestedAttribute": {"v": "OutBRP"},
                "RequestedAttributeValue": {
                    "v": f"{out_brp}",
                    "codingScheme": f"{brp_scheme}",
                },
            }
        )
    if agreement_id:
        rc_list.append(
            {
                "RequestedAttribute": {"v": "AgreementID"},
                "RequestedAttributeValue": {"v": f"{agreement_id}"},
            }
        )
    if mba:
        rc_list.append(
            {
                "RequestedAttribute": {"v": "MBA"},
                "RequestedAttributeValue": {"v": f"{mba}", "codingScheme": "A01"},
            }
        )

    request = {
        "DocumentIdentification": {"v": "1"},
        "DocumentType": {"v": "A25"},
        "SenderIdentification": {
            "v": f"{sender_id}",
            "codingScheme": f"{sender_coding}",
        },
        "SenderRole": {"v": "A08"},
        "ReceiverIdentification": {"v": " ", "codingScheme": "A01"},
        "ReceiverRole": {"v": "A05"},
        "CreationDateTime": {
            "v": datetime.now(timezone.utc)
            .replace(microsecond=0)
            .strftime("%Y-%m-%dT%H:%M:%SZ")
        },
        "RequestComponent": rc_list,
    }
    return self.client.service.GetData(request=request)

get_capacity_reserves(start_time_utc, end_time_utc, time_resolution, business_type, reason_code, mba=None)

Fetch Capacity Reserves (CRE) data for reserve capacity procurement and allocation.

Retrieves information about reserved capacity that is procured by TSOs for maintaining system security and balance, including capacity volumes and prices.

Parameters:

Name	Type	Description	Default
start_time_utc	datetime	Start time in UTC (tz-aware datetime).	required
end_time_utc	datetime	End time in UTC (tz-aware datetime).	required
time_resolution	str	ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.	required
business_type	str	Business type code (e.g., "A95" for frequency restoration).	required
reason_code	str	Reason code for capacity reservation (e.g., "A01").	required
mba	Optional[str]	Optional Metering Balance Area identifier.	None

Returns:

Type	Description
Any	SOAP response object containing capacity reserves data.

Raises:

Type	Description
Exception	If SOAP service call fails.
ValueError	If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

Example

from datetime import datetime, timezone
api = SoapApiClient(area="FI")
result = api.get_capacity_reserves(
    start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
    end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
    time_resolution="PT1H",
    business_type="A95",
    reason_code="A01",
    mba="NO_MBA_001"
)

Source code in physical_operations_utils/esett_utils/eSettSoapApi.py

def get_capacity_reserves(
    self,
    start_time_utc: datetime,
    end_time_utc: datetime,
    time_resolution: str,
    business_type: str,
    reason_code: str,
    mba: Optional[str] = None,
) -> Any:
    """
    Fetch **Capacity Reserves (CRE)** data for reserve capacity procurement and allocation.

    Retrieves information about reserved capacity that is procured by TSOs for
    maintaining system security and balance, including capacity volumes and prices.

    Args:
        start_time_utc: Start time in UTC (tz-aware datetime).
        end_time_utc: End time in UTC (tz-aware datetime).
        time_resolution: ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.
        business_type: Business type code (e.g., `"A95"` for frequency restoration).
        reason_code: Reason code for capacity reservation (e.g., `"A01"`).
        mba: Optional Metering Balance Area identifier.

    Returns:
        SOAP response object containing capacity reserves data.

    Raises:
        Exception: If SOAP service call fails.
        ValueError: If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

    Example:
        ```python
        from datetime import datetime, timezone
        api = SoapApiClient(area="FI")
        result = api.get_capacity_reserves(
            start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
            end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
            time_resolution="PT1H",
            business_type="A95",
            reason_code="A01",
            mba="NO_MBA_001"
        )
        ```
    """
    # Validate input parameters
    self._validate_datetime_parameters(start_time_utc, end_time_utc)
    self._validate_time_resolution(time_resolution)

    sender_coding = self.coding_scheme[self.area]
    sender_id = self.sender_indentification[self.area]
    rc_list = [
        {
            "RequestedAttribute": {"v": "DataFlow"},
            "RequestedAttributeValue": {"v": "CRE"},
        },
        {
            "RequestedAttribute": {"v": "TimeInterval"},
            "RequestedAttributeValue": {
                "v": f"{start_time_utc.isoformat()}Z/{end_time_utc.isoformat()}Z"
            },
        },
        {
            "RequestedAttribute": {"v": "TimeResolution"},
            "RequestedAttributeValue": {"v": f"{time_resolution}"},
        },
        {
            "RequestedAttribute": {"v": "BusinessType"},
            "RequestedAttributeValue": {"v": f"{business_type}"},
        },
        {
            "RequestedAttribute": {"v": "ReasonCode"},
            "RequestedAttributeValue": {"v": f"{reason_code}"},
        },
    ]
    if mba:
        rc_list.append(
            {
                "RequestedAttribute": {"v": "MBA"},
                "RequestedAttributeValue": {"v": f"{mba}", "codingScheme": "A01"},
            }
        )

    request = {
        "DocumentIdentification": {"v": "1"},
        "DocumentType": {"v": "A25"},
        "SenderIdentification": {
            "v": f"{sender_id}",
            "codingScheme": f"{sender_coding}",
        },
        "SenderRole": {"v": "A08"},  # "A46" if BSP context applies【60-25】
        "ReceiverIdentification": {"v": " ", "codingScheme": "A01"},
        "ReceiverRole": {"v": "A05"},
        "CreationDateTime": {
            "v": datetime.now(timezone.utc)
            .replace(microsecond=0)
            .strftime("%Y-%m-%dT%H:%M:%SZ")
        },
        "RequestComponent": rc_list,
    }
    return self.client.service.GetData(request=request)

get_consumption(start_time_utc, end_time_utc, time_resolution, mba=None)

Fetch Consumption (REC) data for electricity consumption by area.

Retrieves measured electricity consumption data used for settlement calculations and grid balancing. Data represents actual consumption by end users.

Parameters:

Name	Type	Description	Default
start_time_utc	datetime	Start time in UTC (tz-aware datetime).	required
end_time_utc	datetime	End time in UTC (tz-aware datetime).	required
time_resolution	str	ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.	required
mba	Optional[str]	Optional Metering Grid Area identifier for filtering.	None

Returns:

Type	Description
Any	SOAP response object containing consumption data.

Raises:

Type	Description
Exception	If SOAP service call fails.
ValueError	If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

Example

from datetime import datetime, timezone
api = SoapApiClient(area="FI")
result = api.get_consumption(
    start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
    end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
    time_resolution="PT1H",
    mba="FI_MGA_001"
)

Source code in physical_operations_utils/esett_utils/eSettSoapApi.py

def get_consumption(
    self,
    start_time_utc: datetime,
    end_time_utc: datetime,
    time_resolution: str,
    mba: Optional[str] = None,
) -> Any:
    """
    Fetch **Consumption (REC)** data for electricity consumption by area.

    Retrieves measured electricity consumption data used for settlement calculations
    and grid balancing. Data represents actual consumption by end users.

    Args:
        start_time_utc: Start time in UTC (tz-aware datetime).
        end_time_utc: End time in UTC (tz-aware datetime).
        time_resolution: ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.
        mba: Optional Metering Grid Area identifier for filtering.

    Returns:
        SOAP response object containing consumption data.

    Raises:
        Exception: If SOAP service call fails.
        ValueError: If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

    Example:
        ```python
        from datetime import datetime, timezone
        api = SoapApiClient(area="FI")
        result = api.get_consumption(
            start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
            end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
            time_resolution="PT1H",
            mba="FI_MGA_001"
        )
        ```
    """
    # Validate input parameters
    self._validate_datetime_parameters(start_time_utc, end_time_utc)
    self._validate_time_resolution(time_resolution)
    sender_coding = self.coding_scheme[self.area]
    sender_id = self.sender_indentification[self.area]
    rc_list = [
        {
            "RequestedAttribute": {"v": "DataFlow"},
            "RequestedAttributeValue": {"v": "REC"},
        },
        {
            "RequestedAttribute": {"v": "TimeInterval"},
            "RequestedAttributeValue": {
                "v": f"{start_time_utc.isoformat()}Z/{end_time_utc.isoformat()}Z"
            },
        },
        {
            "RequestedAttribute": {"v": "TimeResolution"},
            "RequestedAttributeValue": {"v": f"{time_resolution}"},
        },
    ]
    if mba:
        rc_list.append(
            {
                "RequestedAttribute": {"v": "MGA"},
                "RequestedAttributeValue": {"v": f"{mba}", "codingScheme": "A01"},
            }
        )
    request = {
        "DocumentIdentification": {"v": "1"},
        "DocumentType": {"v": "A25"},
        "SenderIdentification": {
            "v": f"{sender_id}",
            "codingScheme": f"{sender_coding}",
        },
        "SenderRole": {"v": "A08"},
        "ReceiverIdentification": {"v": " ", "codingScheme": "A01"},
        "ReceiverRole": {"v": "A05"},
        "CreationDateTime": {
            "v": datetime.now(timezone.utc)
            .replace(microsecond=0)
            .strftime("%Y-%m-%dT%H:%M:%SZ")
        },
        "RequestComponent": rc_list,
    }
    return self.client.service.GetData(request=request)

get_consumption_imbalance(start_time_utc, end_time_utc, time_resolution)

Fetch Consumption Imbalance (CIM) data for consumption forecast deviations.

Retrieves information about imbalances between forecasted and actual electricity consumption, used for settlement calculations and grid balancing.

Parameters:

Name	Type	Description	Default
start_time_utc	datetime	Start time in UTC (tz-aware datetime).	required
end_time_utc	datetime	End time in UTC (tz-aware datetime).	required
time_resolution	str	ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.	required

Returns:

Type	Description
Any	SOAP response object containing consumption imbalance data.

Raises:

Type	Description
Exception	If SOAP service call fails.
ValueError	If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

Example

from datetime import datetime, timezone
api = SoapApiClient(area="FI")
result = api.get_consumption_imbalance(
    start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
    end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
    time_resolution="PT15M",

)

Source code in physical_operations_utils/esett_utils/eSettSoapApi.py

def get_consumption_imbalance(
    self,
    start_time_utc: datetime,
    end_time_utc: datetime,
    time_resolution: str,
) -> Any:
    """
    Fetch **Consumption Imbalance (CIM)** data for consumption forecast deviations.

    Retrieves information about imbalances between forecasted and actual electricity
    consumption, used for settlement calculations and grid balancing.

    Args:
        start_time_utc: Start time in UTC (tz-aware datetime).
        end_time_utc: End time in UTC (tz-aware datetime).
        time_resolution: ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.

    Returns:
        SOAP response object containing consumption imbalance data.

    Raises:
        Exception: If SOAP service call fails.
        ValueError: If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

    Example:
        ```python
        from datetime import datetime, timezone
        api = SoapApiClient(area="FI")
        result = api.get_consumption_imbalance(
            start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
            end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
            time_resolution="PT15M",

        )
        ```
    """
    # Validate input parameters
    self._validate_datetime_parameters(start_time_utc, end_time_utc)
    self._validate_time_resolution(time_resolution)
    sender_coding = self.coding_scheme[self.area]
    sender_id = self.sender_indentification[self.area]
    request = {
        "DocumentIdentification": {"v": "1"},
        "DocumentType": {"v": "A25"},
        "SenderIdentification": {
            "v": f"{sender_id}",
            "codingScheme": f"{sender_coding}",
        },
        "SenderRole": {"v": "A08"},
        "ReceiverIdentification": {"v": " ", "codingScheme": "A01"},
        "ReceiverRole": {"v": "A05"},
        "CreationDateTime": {
            "v": datetime.now(timezone.utc)
            .replace(microsecond=0)
            .strftime("%Y-%m-%dT%H:%M:%SZ")
        },
        "RequestComponent": [
            {
                "RequestedAttribute": {"v": "DataFlow"},
                "RequestedAttributeValue": {"v": "CIM"},
            },
            {
                "RequestedAttribute": {"v": "TimeInterval"},
                "RequestedAttributeValue": {
                    "v": f"{start_time_utc.isoformat()}Z/{end_time_utc.isoformat()}Z"
                },
            },
            {
                "RequestedAttribute": {"v": "TimeResolution"},
                "RequestedAttributeValue": {"v": f"{time_resolution}"},
            },
        ],
    }
    return self.client.service.GetData(request=request)

get_imbalance(start_time_utc, end_time_utc, time_resolution)

Fetch Imbalance (IM) data for system-wide balance deviations.

Retrieves comprehensive imbalance data showing the difference between planned and actual electricity supply/demand, used for settlement and grid management.

Parameters:

Name	Type	Description	Default
start_time_utc	datetime	Start time in UTC (tz-aware datetime).	required
end_time_utc	datetime	End time in UTC (tz-aware datetime).	required
time_resolution	str	ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.	required

Returns:

Type	Description
Any	SOAP response object containing imbalance data.

Raises:

Type	Description
Exception	If SOAP service call fails.
ValueError	If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

Example

from datetime import datetime, timezone
api = SoapApiClient(area="FI")
result = api.get_imbalance(
    start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
    end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
    time_resolution="PT15M",

)

Source code in physical_operations_utils/esett_utils/eSettSoapApi.py

def get_imbalance(
    self,
    start_time_utc: datetime,
    end_time_utc: datetime,
    time_resolution: str,
) -> Any:
    """
    Fetch **Imbalance (IM)** data for system-wide balance deviations.

    Retrieves comprehensive imbalance data showing the difference between planned
    and actual electricity supply/demand, used for settlement and grid management.

    Args:
        start_time_utc: Start time in UTC (tz-aware datetime).
        end_time_utc: End time in UTC (tz-aware datetime).
        time_resolution: ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.

    Returns:
        SOAP response object containing imbalance data.

    Raises:
        Exception: If SOAP service call fails.
        ValueError: If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

    Example:
        ```python
        from datetime import datetime, timezone
        api = SoapApiClient(area="FI")
        result = api.get_imbalance(
            start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
            end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
            time_resolution="PT15M",

        )
        ```
    """
    # Validate input parameters
    self._validate_datetime_parameters(start_time_utc, end_time_utc)
    self._validate_time_resolution(time_resolution)

    sender_coding = self.coding_scheme[self.area]
    sender_id = self.sender_indentification[self.area]
    request = {
        "DocumentIdentification": {"v": "1"},
        "DocumentType": {"v": "A25"},
        "SenderIdentification": {
            "v": f"{sender_id}",
            "codingScheme": f"{sender_coding}",
        },
        "SenderRole": {"v": "A08"},
        "ReceiverIdentification": {"v": " ", "codingScheme": "A01"},
        "ReceiverRole": {"v": "A05"},
        "CreationDateTime": {
            "v": datetime.now(timezone.utc)
            .replace(microsecond=0)
            .strftime("%Y-%m-%dT%H:%M:%SZ")
        },
        "RequestComponent": [
            {
                "RequestedAttribute": {"v": "DataFlow"},
                "RequestedAttributeValue": {"v": "IM"},
            },
            {
                "RequestedAttribute": {"v": "TimeInterval"},
                "RequestedAttributeValue": {
                    "v": f"{start_time_utc.isoformat()}Z/{end_time_utc.isoformat()}Z"
                },
            },
            {
                "RequestedAttribute": {"v": "TimeResolution"},
                "RequestedAttributeValue": {"v": f"{time_resolution}"},
            },
        ],
    }
    return self.client.service.GetData(request=request)

get_imbalance_adjustments(start_time_utc, end_time_utc, time_resolution)

Fetch Imbalance Adjustment (IBA) data for a specified time period.

Returns raw SOAP response containing imbalance adjustment information used for settlement calculations in the Nordic electricity market.

Parameters:

Name	Type	Description	Default
start_time_utc	datetime	Start time in UTC (tz-aware datetime).	required
end_time_utc	datetime	End time in UTC (tz-aware datetime).	required
time_resolution	str	ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.	required

Returns:

Type	Description
Any	SOAP response object containing imbalance adjustment data.

Raises:

Type	Description
Exception	If SOAP service call fails.
ValueError	If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

Example

from datetime import datetime, timezone
api = SoapApiClient(area="FI")
result = api.get_imbalance_adjustments(
    start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
    end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
    time_resolution="PT15M"
)

Source code in physical_operations_utils/esett_utils/eSettSoapApi.py

def get_imbalance_adjustments(
    self, start_time_utc: datetime, end_time_utc: datetime, time_resolution: str
) -> Any:
    """
    Fetch **Imbalance Adjustment (IBA)** data for a specified time period.

    Returns raw SOAP response containing imbalance adjustment information used for
    settlement calculations in the Nordic electricity market.

    Args:
        start_time_utc: Start time in UTC (tz-aware datetime).
        end_time_utc: End time in UTC (tz-aware datetime).
        time_resolution: ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.

    Returns:
        SOAP response object containing imbalance adjustment data.

    Raises:
        Exception: If SOAP service call fails.
        ValueError: If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

    Example:
        ```python
        from datetime import datetime, timezone
        api = SoapApiClient(area="FI")
        result = api.get_imbalance_adjustments(
            start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
            end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
            time_resolution="PT15M"
        )
        ```
    """
    # Validate input parameters
    self._validate_datetime_parameters(start_time_utc, end_time_utc)
    self._validate_time_resolution(time_resolution)

    sender_coding = self.coding_scheme[self.area]
    sender_id = self.sender_indentification[self.area]
    request = {
        "DocumentIdentification": {"v": "1"},
        "DocumentType": {"v": "A25"},
        "SenderIdentification": {
            "v": f"{sender_id}",
            "codingScheme": f"{sender_coding}",
        },
        "SenderRole": {"v": "A08"},
        "ReceiverIdentification": {"v": " ", "codingScheme": "A01"},
        "ReceiverRole": {"v": "A05"},
        "CreationDateTime": {
            "v": datetime.now(timezone.utc)
            .replace(microsecond=0)
            .strftime("%Y-%m-%dT%H:%M:%SZ")
        },
        "RequestComponent": [
            {
                "RequestedAttribute": {"v": "DataFlow"},
                "RequestedAttributeValue": {"v": "IBA"},
            },
            {
                "RequestedAttribute": {"v": "TimeInterval"},
                "RequestedAttributeValue": {
                    "v": f"{start_time_utc.isoformat()}Z/{end_time_utc.isoformat()}Z"
                },
            },
            {
                "RequestedAttribute": {"v": "TimeResolution"},
                "RequestedAttributeValue": {"v": f"{time_resolution}"},
            },
        ],
    }
    return self.client.service.GetData(request=request)

get_merged_production(start_time_utc, end_time_utc, time_resolution, party_re=None, party_re_scheme='A12', mba=None, asset_type=None, production_type=None)

Fetch Merged Production (MPR) data aggregated across multiple production units.

Retrieves consolidated production data that combines output from multiple generation units, typically used for settlement and grid balancing calculations.

Parameters:

Name	Type	Description	Default
start_time_utc	datetime	Start time in UTC (tz-aware datetime).	required
end_time_utc	datetime	End time in UTC (tz-aware datetime).	required
time_resolution	str	ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.	required
party_re	Optional[str]	Optional responsible entity (retailer) identifier.	None
party_re_scheme	str	Coding scheme for party_re (default "A12").	'A12'
mba	Optional[str]	Optional Metering Grid Area identifier.	None
asset_type	Optional[str]	Optional asset type filter (e.g., "WIND", "SOLAR").	None
production_type	Optional[str]	Optional production type filter (e.g., "RENEWABLE").	None

Returns:

Type	Description
Any	SOAP response object containing merged production data.

Raises:

Type	Description
Exception	If SOAP service call fails.
ValueError	If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

Example

from datetime import datetime, timezone
api = SoapApiClient(area="FI")
result = api.get_merged_production(
    start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
    end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
    time_resolution="PT1H",
party_re="PARTY123",
asset_type="WIND",
production_type="RENEWABLE"
)

Source code in physical_operations_utils/esett_utils/eSettSoapApi.py

def get_merged_production(
    self,
    start_time_utc: datetime,
    end_time_utc: datetime,
    time_resolution: str,
    party_re: Optional[str] = None,
    party_re_scheme: str = "A12",
    mba: Optional[str] = None,
    asset_type: Optional[str] = None,
    production_type: Optional[str] = None,
) -> Any:
    """
    Fetch **Merged Production (MPR)** data aggregated across multiple production units.

    Retrieves consolidated production data that combines output from multiple generation
    units, typically used for settlement and grid balancing calculations.

    Args:
        start_time_utc: Start time in UTC (tz-aware datetime).
        end_time_utc: End time in UTC (tz-aware datetime).
        time_resolution: ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.
        party_re: Optional responsible entity (retailer) identifier.
        party_re_scheme: Coding scheme for party_re (default `"A12"`).
        mba: Optional Metering Grid Area identifier.
        asset_type: Optional asset type filter (e.g., `"WIND"`, `"SOLAR"`).
        production_type: Optional production type filter (e.g., `"RENEWABLE"`).

    Returns:
        SOAP response object containing merged production data.

    Raises:
        Exception: If SOAP service call fails.
        ValueError: If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

    Example:
        ```python
        from datetime import datetime, timezone
        api = SoapApiClient(area="FI")
        result = api.get_merged_production(
            start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
            end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
            time_resolution="PT1H",
        party_re="PARTY123",
        asset_type="WIND",
        production_type="RENEWABLE"
        )
        ```
    """
    # Validate input parameters
    self._validate_datetime_parameters(start_time_utc, end_time_utc)
    self._validate_time_resolution(time_resolution)
    sender_coding = self.coding_scheme[self.area]
    sender_id = self.sender_indentification[self.area]
    rc_list = [
        {
            "RequestedAttribute": {"v": "DataFlow"},
            "RequestedAttributeValue": {"v": "MPR"},
        },
        {
            "RequestedAttribute": {"v": "TimeInterval"},
            "RequestedAttributeValue": {
                "v": f"{start_time_utc.isoformat()}Z/{end_time_utc.isoformat()}Z"
            },
        },
        {
            "RequestedAttribute": {"v": "TimeResolution"},
            "RequestedAttributeValue": {"v": f"{time_resolution}"},
        },
    ]
    if party_re:
        rc_list.append(
            {
                "RequestedAttribute": {"v": "PartyRE"},
                "RequestedAttributeValue": {
                    "v": f"{party_re}",
                    "codingScheme": f"{party_re_scheme}",
                },
            }
        )
    if mba:
        rc_list.append(
            {
                "RequestedAttribute": {"v": "MGA"},
                "RequestedAttributeValue": {"v": f"{mba}", "codingScheme": "A01"},
            }
        )
    if asset_type:
        rc_list.append(
            {
                "RequestedAttribute": {"v": "AssetType"},
                "RequestedAttributeValue": {"v": f"{asset_type}"},
            }
        )
    if production_type:
        rc_list.append(
            {
                "RequestedAttribute": {"v": "Production Type"},
                "RequestedAttributeValue": {"v": f"{production_type}"},
            }
        )

    request = {
        "DocumentIdentification": {"v": "1"},
        "DocumentType": {"v": "A25"},
        "SenderIdentification": {
            "v": f"{sender_id}",
            "codingScheme": f"{sender_coding}",
        },
        "SenderRole": {"v": "A08"},
        "ReceiverIdentification": {"v": " ", "codingScheme": "A01"},
        "ReceiverRole": {"v": "A05"},
        "CreationDateTime": {
            "v": datetime.now(timezone.utc)
            .replace(microsecond=0)
            .strftime("%Y-%m-%dT%H:%M:%SZ")
        },
        "RequestComponent": rc_list,
    }
    return self.client.service.GetData(request=request)

get_mga_exchange_trades(start_time_utc, end_time_utc, time_resolution, in_re=None, out_re=None, re_scheme='A12', in_mga=None, out_mga=None)

Fetch MGA Exchange Trades (MGT) data for trades between responsible entities and grid areas.

Retrieves information about electricity trades between responsible entities across different metering grid areas, including trade volumes and pricing.

Parameters:

Name	Type	Description	Default
start_time_utc	datetime	Start time in UTC (tz-aware datetime).	required
end_time_utc	datetime	End time in UTC (tz-aware datetime).	required
time_resolution	str	ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.	required
in_re	Optional[str]	Optional incoming responsible entity identifier.	None
out_re	Optional[str]	Optional outgoing responsible entity identifier.	None
re_scheme	str	Coding scheme for responsible entity IDs (default "A12").	'A12'
in_mga	Optional[str]	Optional source Metering Grid Area identifier.	None
out_mga	Optional[str]	Optional destination Metering Grid Area identifier.	None

Returns:

Type	Description
Any	SOAP response object containing MGA exchange trades data.

Raises:

Type	Description
Exception	If SOAP service call fails.
ValueError	If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

Example

from datetime import datetime, timezone
api = SoapApiClient(area="FI")
result = api.get_mga_exchange_trades(
    start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
    end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
    time_resolution="PT1H",
in_re="RE_001",
out_re="RE_002",
in_mga="SE_MGA_001"
)

Source code in physical_operations_utils/esett_utils/eSettSoapApi.py

def get_mga_exchange_trades(
    self,
    start_time_utc: datetime,
    end_time_utc: datetime,
    time_resolution: str,
    in_re: Optional[str] = None,
    out_re: Optional[str] = None,
    re_scheme: str = "A12",
    in_mga: Optional[str] = None,
    out_mga: Optional[str] = None,
) -> Any:
    """
    Fetch **MGA Exchange Trades (MGT)** data for trades between responsible entities and grid areas.

    Retrieves information about electricity trades between responsible entities
    across different metering grid areas, including trade volumes and pricing.

    Args:
        start_time_utc: Start time in UTC (tz-aware datetime).
        end_time_utc: End time in UTC (tz-aware datetime).
        time_resolution: ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.
        in_re: Optional incoming responsible entity identifier.
        out_re: Optional outgoing responsible entity identifier.
        re_scheme: Coding scheme for responsible entity IDs (default `"A12"`).
        in_mga: Optional source Metering Grid Area identifier.
        out_mga: Optional destination Metering Grid Area identifier.

    Returns:
        SOAP response object containing MGA exchange trades data.

    Raises:
        Exception: If SOAP service call fails.
        ValueError: If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

    Example:
        ```python
        from datetime import datetime, timezone
        api = SoapApiClient(area="FI")
        result = api.get_mga_exchange_trades(
            start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
            end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
            time_resolution="PT1H",
        in_re="RE_001",
        out_re="RE_002",
        in_mga="SE_MGA_001"
        )
        ```
    """
    # Validate input parameters
    self._validate_datetime_parameters(start_time_utc, end_time_utc)
    self._validate_time_resolution(time_resolution)
    sender_coding = self.coding_scheme[self.area]
    sender_id = self.sender_indentification[self.area]
    rc_list = [
        {
            "RequestedAttribute": {"v": "DataFlow"},
            "RequestedAttributeValue": {"v": "MGT"},
        },
        {
            "RequestedAttribute": {"v": "TimeInterval"},
            "RequestedAttributeValue": {
                "v": f"{start_time_utc.isoformat()}Z/{end_time_utc.isoformat()}Z"
            },
        },
        {
            "RequestedAttribute": {"v": "TimeResolution"},
            "RequestedAttributeValue": {"v": f"{time_resolution}"},
        },
    ]
    if in_re:
        rc_list.append(
            {
                "RequestedAttribute": {"v": "InRE"},
                "RequestedAttributeValue": {
                    "v": f"{in_re}",
                    "codingScheme": f"{re_scheme}",
                },
            }
        )
    if out_re:
        rc_list.append(
            {
                "RequestedAttribute": {"v": "OutRE"},
                "RequestedAttributeValue": {
                    "v": f"{out_re}",
                    "codingScheme": f"{re_scheme}",
                },
            }
        )
    if in_mga:
        rc_list.append(
            {
                "RequestedAttribute": {"v": "InMGA"},
                "RequestedAttributeValue": {
                    "v": f"{in_mga}",
                    "codingScheme": "A01",
                },
            }
        )
    if out_mga:
        rc_list.append(
            {
                "RequestedAttribute": {"v": "OutMGA"},
                "RequestedAttributeValue": {
                    "v": f"{out_mga}",
                    "codingScheme": "A01",
                },
            }
        )

    request = {
        "DocumentIdentification": {"v": "1"},
        "DocumentType": {"v": "A25"},
        "SenderIdentification": {
            "v": f"{sender_id}",
            "codingScheme": f"{sender_coding}",
        },
        "SenderRole": {"v": "A08"},
        "ReceiverIdentification": {"v": " ", "codingScheme": "A01"},
        "ReceiverRole": {"v": "A05"},
        "CreationDateTime": {
            "v": datetime.now(timezone.utc)
            .replace(microsecond=0)
            .strftime("%Y-%m-%dT%H:%M:%SZ")
        },
        "RequestComponent": rc_list,
    }
    return self.client.service.GetData(request=request)

get_mga_exchanges(start_time_utc, end_time_utc, time_resolution, in_mga=None, out_mga=None)

Fetch Metering Grid Area (MGA) Exchanges (MGX) data for inter-area electricity transfers.

Retrieves information about electricity exchanges between different metering grid areas, including transfer volumes and settlement data.

Parameters:

Name	Type	Description	Default
start_time_utc	datetime	Start time in UTC (tz-aware datetime).	required
end_time_utc	datetime	End time in UTC (tz-aware datetime).	required
time_resolution	str	ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.	required
in_mga	Optional[str]	Optional source Metering Grid Area identifier.	None
out_mga	Optional[str]	Optional destination Metering Grid Area identifier.	None

Returns:

Type	Description
Any	SOAP response object containing MGA exchanges data.

Raises:

Type	Description
Exception	If SOAP service call fails.
ValueError	If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

Example

from datetime import datetime, timezone
api = SoapApiClient(area="FI")
result = api.get_mga_exchanges(
    start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
    end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
    time_resolution="PT1H",
in_mga="FI_MGA_001",
out_mga="FI_MGA_002"
)

Source code in physical_operations_utils/esett_utils/eSettSoapApi.py

def get_mga_exchanges(
    self,
    start_time_utc: datetime,
    end_time_utc: datetime,
    time_resolution: str,
    in_mga: Optional[str] = None,
    out_mga: Optional[str] = None,
) -> Any:
    """
    Fetch **Metering Grid Area (MGA) Exchanges (MGX)** data for inter-area electricity transfers.

    Retrieves information about electricity exchanges between different metering
    grid areas, including transfer volumes and settlement data.

    Args:
        start_time_utc: Start time in UTC (tz-aware datetime).
        end_time_utc: End time in UTC (tz-aware datetime).
        time_resolution: ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.
        in_mga: Optional source Metering Grid Area identifier.
        out_mga: Optional destination Metering Grid Area identifier.

    Returns:
        SOAP response object containing MGA exchanges data.

    Raises:
        Exception: If SOAP service call fails.
        ValueError: If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

    Example:
        ```python
        from datetime import datetime, timezone
        api = SoapApiClient(area="FI")
        result = api.get_mga_exchanges(
            start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
            end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
            time_resolution="PT1H",
        in_mga="FI_MGA_001",
        out_mga="FI_MGA_002"
        )
        ```
    """
    # Validate input parameters
    self._validate_datetime_parameters(start_time_utc, end_time_utc)
    self._validate_time_resolution(time_resolution)
    sender_coding = self.coding_scheme[self.area]
    sender_id = self.sender_indentification[self.area]
    rc_list = [
        {
            "RequestedAttribute": {"v": "DataFlow"},
            "RequestedAttributeValue": {"v": "MGX"},
        },
        {
            "RequestedAttribute": {"v": "TimeInterval"},
            "RequestedAttributeValue": {
                "v": f"{start_time_utc.isoformat()}Z/{end_time_utc.isoformat()}Z"
            },
        },
        {
            "RequestedAttribute": {"v": "TimeResolution"},
            "RequestedAttributeValue": {"v": f"{time_resolution}"},
        },
    ]
    if in_mga:
        rc_list.append(
            {
                "RequestedAttribute": {"v": "InMGA"},
                "RequestedAttributeValue": {
                    "v": f"{in_mga}",
                    "codingScheme": "A01",
                },
            }
        )
    if out_mga:
        rc_list.append(
            {
                "RequestedAttribute": {"v": "OutMGA"},
                "RequestedAttributeValue": {
                    "v": f"{out_mga}",
                    "codingScheme": "A01",
                },
            }
        )

    request = {
        "DocumentIdentification": {"v": "1"},
        "DocumentType": {"v": "A25"},
        "SenderIdentification": {
            "v": f"{sender_id}",
            "codingScheme": f"{sender_coding}",
        },
        "SenderRole": {"v": "A08"},
        "ReceiverIdentification": {"v": " ", "codingScheme": "A01"},
        "ReceiverRole": {"v": "A05"},
        "CreationDateTime": {
            "v": datetime.now(timezone.utc)
            .replace(microsecond=0)
            .strftime("%Y-%m-%dT%H:%M:%SZ")
        },
        "RequestComponent": rc_list,
    }
    return self.client.service.GetData(request=request)

get_mga_imbalance(start_time_utc, end_time_utc, time_resolution)

Fetch Metering Grid Area Imbalance (MIM) data for grid area balance deviations.

Retrieves information about imbalances within specific metering grid areas, representing the difference between planned and actual energy flows.

Parameters:

Name	Type	Description	Default
start_time_utc	datetime	Start time in UTC (tz-aware datetime).	required
end_time_utc	datetime	End time in UTC (tz-aware datetime).	required
time_resolution	str	ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.	required

Returns:

Type	Description
Any	SOAP response object containing MGA imbalance data.

Raises:

Type	Description
Exception	If SOAP service call fails.
ValueError	If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

Example

from datetime import datetime, timezone
api = SoapApiClient(area="FI")
result = api.get_mga_imbalance(
    start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
    end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
    time_resolution="PT1H",

)

Source code in physical_operations_utils/esett_utils/eSettSoapApi.py

def get_mga_imbalance(
    self,
    start_time_utc: datetime,
    end_time_utc: datetime,
    time_resolution: str,
) -> Any:
    """
    Fetch **Metering Grid Area Imbalance (MIM)** data for grid area balance deviations.

    Retrieves information about imbalances within specific metering grid areas,
    representing the difference between planned and actual energy flows.

    Args:
        start_time_utc: Start time in UTC (tz-aware datetime).
        end_time_utc: End time in UTC (tz-aware datetime).
        time_resolution: ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.

    Returns:
        SOAP response object containing MGA imbalance data.

    Raises:
        Exception: If SOAP service call fails.
        ValueError: If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

    Example:
        ```python
        from datetime import datetime, timezone
        api = SoapApiClient(area="FI")
        result = api.get_mga_imbalance(
            start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
            end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
            time_resolution="PT1H",

        )
        ```
    """
    # Validate input parameters
    self._validate_datetime_parameters(start_time_utc, end_time_utc)
    self._validate_time_resolution(time_resolution)
    sender_coding = self.coding_scheme[self.area]
    sender_id = self.sender_indentification[self.area]
    request = {
        "DocumentIdentification": {"v": "1"},
        "DocumentType": {"v": "A25"},
        "SenderIdentification": {
            "v": f"{sender_id}",
            "codingScheme": f"{sender_coding}",
        },
        "SenderRole": {"v": "A08"},
        "ReceiverIdentification": {"v": " ", "codingScheme": "A01"},
        "ReceiverRole": {"v": "A05"},
        "CreationDateTime": {
            "v": datetime.now(timezone.utc)
            .replace(microsecond=0)
            .strftime("%Y-%m-%dT%H:%M:%SZ")
        },
        "RequestComponent": [
            {
                "RequestedAttribute": {"v": "DataFlow"},
                "RequestedAttributeValue": {"v": "MIM"},
            },
            {
                "RequestedAttribute": {"v": "TimeInterval"},
                "RequestedAttributeValue": {
                    "v": f"{start_time_utc.isoformat()}Z/{end_time_utc.isoformat()}Z"
                },
            },
            {
                "RequestedAttribute": {"v": "TimeResolution"},
                "RequestedAttributeValue": {"v": f"{time_resolution}"},
            },
        ],
    }
    return self.client.service.GetData(request=request)

get_mga_mba_relations(start_time_utc, end_time_utc, time_resolution, sender_role='A18')

Fetch MGA-MBA Relations (ARE) data for grid area relationship mappings.

Retrieves information about relationships between Metering Grid Areas (MGA) and Metering Balance Areas (MBA), used for settlement and grid topology.

Parameters:

Name	Type	Description	Default
start_time_utc	datetime	Start time in UTC (tz-aware datetime).	required
end_time_utc	datetime	End time in UTC (tz-aware datetime).	required
time_resolution	str	ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.	required
sender_role	str	Sender role code (default "A18" for DSO/Datahub/TSO).	'A18'

Returns:

Type	Description
Any	SOAP response object containing MGA-MBA relations data.

Raises:

Type	Description
Exception	If SOAP service call fails.
ValueError	If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

Example

from datetime import datetime, timezone
api = SoapApiClient(area="FI")
result = api.get_mga_mba_relations(
    start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
    end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
    time_resolution="P1D",
,
    sender_role="A18"
)

Source code in physical_operations_utils/esett_utils/eSettSoapApi.py

def get_mga_mba_relations(
    self,
    start_time_utc: datetime,
    end_time_utc: datetime,
    time_resolution: str,
    sender_role: str = "A18",
) -> Any:
    """
    Fetch **MGA-MBA Relations (ARE)** data for grid area relationship mappings.

    Retrieves information about relationships between Metering Grid Areas (MGA)
    and Metering Balance Areas (MBA), used for settlement and grid topology.

    Args:
        start_time_utc: Start time in UTC (tz-aware datetime).
        end_time_utc: End time in UTC (tz-aware datetime).
        time_resolution: ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.
        sender_role: Sender role code (default `"A18"` for DSO/Datahub/TSO).

    Returns:
        SOAP response object containing MGA-MBA relations data.

    Raises:
        Exception: If SOAP service call fails.
        ValueError: If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

    Example:
        ```python
        from datetime import datetime, timezone
        api = SoapApiClient(area="FI")
        result = api.get_mga_mba_relations(
            start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
            end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
            time_resolution="P1D",
        ,
            sender_role="A18"
        )
        ```
    """
    # Validate input parameters
    self._validate_datetime_parameters(start_time_utc, end_time_utc)
    self._validate_time_resolution(time_resolution)
    sender_coding = self.coding_scheme[self.area]
    sender_id = self.sender_indentification[self.area]
    request = {
        "DocumentIdentification": {"v": "1"},
        "DocumentType": {"v": "A25"},
        "SenderIdentification": {
            "v": f"{sender_id}",
            "codingScheme": f"{sender_coding}",
        },
        "SenderRole": {"v": f"{sender_role}"},
        "ReceiverIdentification": {"v": " ", "codingScheme": "A01"},
        "ReceiverRole": {"v": "A05"},
        "CreationDateTime": {
            "v": datetime.now(timezone.utc)
            .replace(microsecond=0)
            .strftime("%Y-%m-%dT%H:%M:%SZ")
        },
        "RequestComponent": [
            {
                "RequestedAttribute": {"v": "DataFlow"},
                "RequestedAttributeValue": {"v": "ARE"},
            },
            {
                "RequestedAttribute": {"v": "TimeInterval"},
                "RequestedAttributeValue": {
                    "v": f"{start_time_utc.isoformat()}Z/{end_time_utc.isoformat()}Z"
                },
            },
            {
                "RequestedAttribute": {"v": "TimeResolution"},
                "RequestedAttributeValue": {"v": f"{time_resolution}"},
            },
        ],
    }
    return self.client.service.GetData(request=request)

get_prices(start_time_utc, end_time_utc, time_resolution)

Fetch Prices (REP) - settlement prices for electricity trading.

Retrieves official settlement prices used for imbalance settlement and financial settlement of electricity trades in the Nordic market.

Parameters:

Name	Type	Description	Default
start_time_utc	datetime	Start time in UTC (tz-aware datetime).	required
end_time_utc	datetime	End time in UTC (tz-aware datetime).	required
time_resolution	str	ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.	required

Returns:

Type	Description
Any	SOAP response object containing settlement price data.

Raises:

Type	Description
Exception	If SOAP service call fails.
ValueError	If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

Example

from datetime import datetime, timezone
api = SoapApiClient(area="FI")
result = api.get_prices(
    start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
    end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
    time_resolution="PT1H",

)

Source code in physical_operations_utils/esett_utils/eSettSoapApi.py

def get_prices(
    self,
    start_time_utc: datetime,
    end_time_utc: datetime,
    time_resolution: str,
) -> Any:
    """
    Fetch **Prices (REP)** - settlement prices for electricity trading.

    Retrieves official settlement prices used for imbalance settlement and financial
    settlement of electricity trades in the Nordic market.

    Args:
        start_time_utc: Start time in UTC (tz-aware datetime).
        end_time_utc: End time in UTC (tz-aware datetime).
        time_resolution: ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.

    Returns:
        SOAP response object containing settlement price data.

    Raises:
        Exception: If SOAP service call fails.
        ValueError: If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

    Example:
        ```python
        from datetime import datetime, timezone
        api = SoapApiClient(area="FI")
        result = api.get_prices(
            start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
            end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
            time_resolution="PT1H",

        )
        ```
    """
    # Validate input parameters
    self._validate_datetime_parameters(start_time_utc, end_time_utc)
    self._validate_time_resolution(time_resolution)
    sender_coding = self.coding_scheme[self.area]
    sender_id = self.sender_indentification[self.area]
    request = {
        "DocumentIdentification": {"v": "1"},
        "DocumentType": {"v": "A25"},
        "SenderIdentification": {
            "v": f"{sender_id}",
            "codingScheme": f"{sender_coding}",
        },
        "SenderRole": {"v": "A08"},
        "ReceiverIdentification": {"v": " ", "codingScheme": "A01"},
        "ReceiverRole": {"v": "A05"},
        "CreationDateTime": {
            "v": datetime.now(timezone.utc)
            .replace(microsecond=0)
            .strftime("%Y-%m-%dT%H:%M:%SZ")
        },
        "RequestComponent": [
            {
                "RequestedAttribute": {"v": "DataFlow"},
                "RequestedAttributeValue": {"v": "REP"},
            },
            {
                "RequestedAttribute": {"v": "TimeInterval"},
                "RequestedAttributeValue": {
                    "v": f"{start_time_utc.isoformat()}Z/{end_time_utc.isoformat()}Z"
                },
            },
            {
                "RequestedAttribute": {"v": "TimeResolution"},
                "RequestedAttributeValue": {"v": f"{time_resolution}"},
            },
        ],
    }
    return self.client.service.GetData(request=request)

get_production(start_time_utc, end_time_utc, time_resolution, mba=None)

Fetch Production (RPM) data for electricity generation by area.

Retrieves measured electricity production data from generation units, used for settlement calculations and grid balancing. Data represents actual generation output.

Parameters:

Name	Type	Description	Default
start_time_utc	datetime	Start time in UTC (tz-aware datetime).	required
end_time_utc	datetime	End time in UTC (tz-aware datetime).	required
time_resolution	str	ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.	required
mba	Optional[str]	Optional Metering Grid Area identifier for filtering.	None

Returns:

Type	Description
Any	SOAP response object containing production data.

Raises:

Type	Description
Exception	If SOAP service call fails.
ValueError	If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

Example

from datetime import datetime, timezone
api = SoapApiClient(area="FI")
result = api.get_production(
    start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
    end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
    time_resolution="PT1H",
    mba="SE_MGA_001"
)

Source code in physical_operations_utils/esett_utils/eSettSoapApi.py

def get_production(
    self,
    start_time_utc: datetime,
    end_time_utc: datetime,
    time_resolution: str,
    mba: Optional[str] = None,
) -> Any:
    """
    Fetch **Production (RPM)** data for electricity generation by area.

    Retrieves measured electricity production data from generation units, used for
    settlement calculations and grid balancing. Data represents actual generation output.

    Args:
        start_time_utc: Start time in UTC (tz-aware datetime).
        end_time_utc: End time in UTC (tz-aware datetime).
        time_resolution: ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.
        mba: Optional Metering Grid Area identifier for filtering.

    Returns:
        SOAP response object containing production data.

    Raises:
        Exception: If SOAP service call fails.
        ValueError: If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

    Example:
        ```python
        from datetime import datetime, timezone
        api = SoapApiClient(area="FI")
        result = api.get_production(
            start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
            end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
            time_resolution="PT1H",
            mba="SE_MGA_001"
        )
        ```
    """
    # Validate input parameters
    self._validate_datetime_parameters(start_time_utc, end_time_utc)
    self._validate_time_resolution(time_resolution)
    sender_coding = self.coding_scheme[self.area]
    sender_id = self.sender_indentification[self.area]
    rc_list = [
        {
            "RequestedAttribute": {"v": "DataFlow"},
            "RequestedAttributeValue": {"v": "RPM"},
        },
        {
            "RequestedAttribute": {"v": "TimeInterval"},
            "RequestedAttributeValue": {
                "v": f"{start_time_utc.isoformat()}Z/{end_time_utc.isoformat()}Z"
            },
        },
        {
            "RequestedAttribute": {"v": "TimeResolution"},
            "RequestedAttributeValue": {"v": f"{time_resolution}"},
        },
    ]
    if mba:
        rc_list.append(
            {
                "RequestedAttribute": {"v": "MGA"},
                "RequestedAttributeValue": {"v": f"{mba}", "codingScheme": "A01"},
            }
        )
    request = {
        "DocumentIdentification": {"v": "1"},
        "DocumentType": {"v": "A25"},
        "SenderIdentification": {
            "v": f"{sender_id}",
            "codingScheme": f"{sender_coding}",
        },
        "SenderRole": {"v": "A08"},
        "ReceiverIdentification": {"v": " ", "codingScheme": "A01"},
        "ReceiverRole": {"v": "A05"},
        "CreationDateTime": {
            "v": datetime.now(timezone.utc)
            .replace(microsecond=0)
            .strftime("%Y-%m-%dT%H:%M:%SZ")
        },
        "RequestComponent": rc_list,
    }
    return self.client.service.GetData(request=request)

get_production_imbalance(start_time_utc, end_time_utc, time_resolution)

Fetch Production Imbalance (PIM) data for production forecast deviations.

Retrieves information about imbalances between forecasted and actual electricity production, used for settlement calculations and grid balancing.

Parameters:

Name	Type	Description	Default
start_time_utc	datetime	Start time in UTC (tz-aware datetime).	required
end_time_utc	datetime	End time in UTC (tz-aware datetime).	required
time_resolution	str	ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.	required

Returns:

Type	Description
Any	SOAP response object containing production imbalance data.

Raises:

Type	Description
Exception	If SOAP service call fails.
ValueError	If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

Example

from datetime import datetime, timezone
api = SoapApiClient(area="FI")
result = api.get_production_imbalance(
    start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
    end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
    time_resolution="PT15M",

)

Source code in physical_operations_utils/esett_utils/eSettSoapApi.py

def get_production_imbalance(
    self,
    start_time_utc: datetime,
    end_time_utc: datetime,
    time_resolution: str,
) -> Any:
    """
    Fetch **Production Imbalance (PIM)** data for production forecast deviations.

    Retrieves information about imbalances between forecasted and actual electricity
    production, used for settlement calculations and grid balancing.

    Args:
        start_time_utc: Start time in UTC (tz-aware datetime).
        end_time_utc: End time in UTC (tz-aware datetime).
        time_resolution: ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.

    Returns:
        SOAP response object containing production imbalance data.

    Raises:
        Exception: If SOAP service call fails.
        ValueError: If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

    Example:
        ```python
        from datetime import datetime, timezone
        api = SoapApiClient(area="FI")
        result = api.get_production_imbalance(
            start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
            end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
            time_resolution="PT15M",

        )
        ```
    """
    # Validate input parameters
    self._validate_datetime_parameters(start_time_utc, end_time_utc)
    self._validate_time_resolution(time_resolution)
    sender_coding = self.coding_scheme[self.area]
    sender_id = self.sender_indentification[self.area]
    request = {
        "DocumentIdentification": {"v": "1"},
        "DocumentType": {"v": "A25"},
        "SenderIdentification": {
            "v": f"{sender_id}",
            "codingScheme": f"{sender_coding}",
        },
        "SenderRole": {"v": "A08"},
        "ReceiverIdentification": {"v": " ", "codingScheme": "A01"},
        "ReceiverRole": {"v": "A05"},
        "CreationDateTime": {
            "v": datetime.now(timezone.utc)
            .replace(microsecond=0)
            .strftime("%Y-%m-%dT%H:%M:%SZ")
        },
        "RequestComponent": [
            {
                "RequestedAttribute": {"v": "DataFlow"},
                "RequestedAttributeValue": {"v": "PIM"},
            },
            {
                "RequestedAttribute": {"v": "TimeInterval"},
                "RequestedAttributeValue": {
                    "v": f"{start_time_utc.isoformat()}Z/{end_time_utc.isoformat()}Z"
                },
            },
            {
                "RequestedAttribute": {"v": "TimeResolution"},
                "RequestedAttributeValue": {"v": f"{time_resolution}"},
            },
        ],
    }
    return self.client.service.GetData(request=request)

get_production_per_unit_type_mga(start_time_utc, end_time_utc, time_resolution)

Fetch Production per Unit Type and MGA (PROD_MGA_PUT) data for categorized production.

Retrieves production data categorized by production unit types within specific Metering Grid Areas, used for renewable energy tracking and settlement.

Parameters:

Name	Type	Description	Default
start_time_utc	datetime	Start time in UTC (tz-aware datetime).	required
end_time_utc	datetime	End time in UTC (tz-aware datetime).	required
time_resolution	str	ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.	required

Returns:

Type	Description
Any	SOAP response object containing production per unit type and MGA data.

Raises:

Type	Description
Exception	If SOAP service call fails.
ValueError	If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

Example

from datetime import datetime, timezone
api = SoapApiClient(area="FI")
result = api.get_production_per_unit_type_mga(
    start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
    end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
    time_resolution="PT1H",

)

Source code in physical_operations_utils/esett_utils/eSettSoapApi.py

def get_production_per_unit_type_mga(
    self,
    start_time_utc: datetime,
    end_time_utc: datetime,
    time_resolution: str,
) -> Any:
    """
    Fetch **Production per Unit Type and MGA (PROD_MGA_PUT)** data for categorized production.

    Retrieves production data categorized by production unit types within specific
    Metering Grid Areas, used for renewable energy tracking and settlement.

    Args:
        start_time_utc: Start time in UTC (tz-aware datetime).
        end_time_utc: End time in UTC (tz-aware datetime).
        time_resolution: ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.

    Returns:
        SOAP response object containing production per unit type and MGA data.

    Raises:
        Exception: If SOAP service call fails.
        ValueError: If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

    Example:
        ```python
        from datetime import datetime, timezone
        api = SoapApiClient(area="FI")
        result = api.get_production_per_unit_type_mga(
            start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
            end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
            time_resolution="PT1H",

        )
        ```
    """
    # Validate input parameters
    self._validate_datetime_parameters(start_time_utc, end_time_utc)
    self._validate_time_resolution(time_resolution)
    sender_coding = self.coding_scheme[self.area]
    sender_id = self.sender_indentification[self.area]
    request = {
        "DocumentIdentification": {"v": "1"},
        "DocumentType": {"v": "A25"},
        "SenderIdentification": {
            "v": f"{sender_id}",
            "codingScheme": f"{sender_coding}",
        },
        "SenderRole": {"v": "A08"},
        "ReceiverIdentification": {"v": " ", "codingScheme": "A01"},
        "ReceiverRole": {"v": "A05"},
        "CreationDateTime": {
            "v": datetime.now(timezone.utc)
            .replace(microsecond=0)
            .strftime("%Y-%m-%dT%H:%M:%SZ")
        },
        "RequestComponent": [
            {
                "RequestedAttribute": {"v": "DataFlow"},
                "RequestedAttributeValue": {"v": "PROD_MGA_PUT"},
            },
            {
                "RequestedAttribute": {"v": "TimeInterval"},
                "RequestedAttributeValue": {
                    "v": f"{start_time_utc.isoformat()}Z/{end_time_utc.isoformat()}Z"
                },
            },
            {
                "RequestedAttribute": {"v": "TimeResolution"},
                "RequestedAttributeValue": {"v": f"{time_resolution}"},
            },
        ],
    }
    return self.client.service.GetData(request=request)

get_production_plan(start_time_utc, end_time_utc, time_resolution)

Fetch Production Plan (PRP) data for planned electricity generation.

Retrieves planned production schedules submitted by generators, used for comparing against actual production and calculating imbalances.

Parameters:

Name	Type	Description	Default
start_time_utc	datetime	Start time in UTC (tz-aware datetime).	required
end_time_utc	datetime	End time in UTC (tz-aware datetime).	required
time_resolution	str	ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.	required

Returns:

Type	Description
Any	SOAP response object containing production plan data.

Raises:

Type	Description
Exception	If SOAP service call fails.
ValueError	If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

Example

from datetime import datetime, timezone
api = SoapApiClient(area="FI")
result = api.get_production_plan(
    start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
    end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
    time_resolution="PT1H",

)

Source code in physical_operations_utils/esett_utils/eSettSoapApi.py

def get_production_plan(
    self,
    start_time_utc: datetime,
    end_time_utc: datetime,
    time_resolution: str,
) -> Any:
    """
    Fetch **Production Plan (PRP)** data for planned electricity generation.

    Retrieves planned production schedules submitted by generators, used for
    comparing against actual production and calculating imbalances.

    Args:
        start_time_utc: Start time in UTC (tz-aware datetime).
        end_time_utc: End time in UTC (tz-aware datetime).
        time_resolution: ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.

    Returns:
        SOAP response object containing production plan data.

    Raises:
        Exception: If SOAP service call fails.
        ValueError: If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

    Example:
        ```python
        from datetime import datetime, timezone
        api = SoapApiClient(area="FI")
        result = api.get_production_plan(
            start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
            end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
            time_resolution="PT1H",

        )
        ```
    """
    # Validate input parameters
    self._validate_datetime_parameters(start_time_utc, end_time_utc)
    self._validate_time_resolution(time_resolution)
    sender_coding = self.coding_scheme[self.area]
    sender_id = self.sender_indentification[self.area]
    request = {
        "DocumentIdentification": {"v": "1"},
        "DocumentType": {"v": "A25"},
        "SenderIdentification": {
            "v": f"{sender_id}",
            "codingScheme": f"{sender_coding}",
        },
        "SenderRole": {"v": "A08"},
        "ReceiverIdentification": {"v": " ", "codingScheme": "A01"},
        "ReceiverRole": {"v": "A05"},
        "CreationDateTime": {
            "v": datetime.now(timezone.utc)
            .replace(microsecond=0)
            .strftime("%Y-%m-%dT%H:%M:%SZ")
        },
        "RequestComponent": [
            {
                "RequestedAttribute": {"v": "DataFlow"},
                "RequestedAttributeValue": {"v": "PRP"},
            },
            {
                "RequestedAttribute": {"v": "TimeInterval"},
                "RequestedAttributeValue": {
                    "v": f"{start_time_utc.isoformat()}Z/{end_time_utc.isoformat()}Z"
                },
            },
            {
                "RequestedAttribute": {"v": "TimeResolution"},
                "RequestedAttributeValue": {"v": f"{time_resolution}"},
            },
        ],
    }
    return self.client.service.GetData(request=request)

get_px_market_flows(start_time_utc, end_time_utc, time_resolution, in_area=None, out_area=None, process_type=None)

Fetch Power Exchange Market Flows (PXF) data for cross-border electricity flows.

Retrieves information about electricity flows between areas traded on power exchanges, including import/export volumes and flow directions.

Parameters:

Name	Type	Description	Default
start_time_utc	datetime	Start time in UTC (tz-aware datetime).	required
end_time_utc	datetime	End time in UTC (tz-aware datetime).	required
time_resolution	str	ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.	required
in_area	Optional[str]	Optional source area for import flows.	None
out_area	Optional[str]	Optional destination area for export flows.	None
process_type	Optional[str]	Optional process type filter for flow categorization.	None

Returns:

Type	Description
Any	SOAP response object containing power exchange market flows data.

Raises:

Type	Description
Exception	If SOAP service call fails.
ValueError	If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

Example

from datetime import datetime, timezone
api = SoapApiClient(area="FI")
result = api.get_px_market_flows(
    start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
    end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
    time_resolution="PT1H",
in_,
out_
)

Source code in physical_operations_utils/esett_utils/eSettSoapApi.py

def get_px_market_flows(
    self,
    start_time_utc: datetime,
    end_time_utc: datetime,
    time_resolution: str,
    in_area: Optional[str] = None,
    out_area: Optional[str] = None,
    process_type: Optional[str] = None,
) -> Any:
    """
    Fetch **Power Exchange Market Flows (PXF)** data for cross-border electricity flows.

    Retrieves information about electricity flows between areas traded on power
    exchanges, including import/export volumes and flow directions.

    Args:
        start_time_utc: Start time in UTC (tz-aware datetime).
        end_time_utc: End time in UTC (tz-aware datetime).
        time_resolution: ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.
        in_area: Optional source area for import flows.
        out_area: Optional destination area for export flows.
        process_type: Optional process type filter for flow categorization.

    Returns:
        SOAP response object containing power exchange market flows data.

    Raises:
        Exception: If SOAP service call fails.
        ValueError: If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

    Example:
        ```python
        from datetime import datetime, timezone
        api = SoapApiClient(area="FI")
        result = api.get_px_market_flows(
            start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
            end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
            time_resolution="PT1H",
        in_,
        out_
        )
        ```
    """
    # Validate input parameters
    self._validate_datetime_parameters(start_time_utc, end_time_utc)
    self._validate_time_resolution(time_resolution)
    sender_coding = self.coding_scheme[self.area]
    sender_id = self.sender_indentification[self.area]
    rc_list = [
        {
            "RequestedAttribute": {"v": "DataFlow"},
            "RequestedAttributeValue": {"v": "PXF"},
        },
        {
            "RequestedAttribute": {"v": "TimeInterval"},
            "RequestedAttributeValue": {
                "v": f"{start_time_utc.isoformat()}Z/{end_time_utc.isoformat()}Z"
            },
        },
        {
            "RequestedAttribute": {"v": "TimeResolution"},
            "RequestedAttributeValue": {"v": f"{time_resolution}"},
        },
    ]
    if in_area:
        rc_list.append(
            {
                "RequestedAttribute": {"v": "InArea"},
                "RequestedAttributeValue": {
                    "v": f"{in_area}",
                    "codingScheme": "A01",
                },
            }
        )
    if out_area:
        rc_list.append(
            {
                "RequestedAttribute": {"v": "OutArea"},
                "RequestedAttributeValue": {
                    "v": f"{out_area}",
                    "codingScheme": "A01",
                },
            }
        )
    if process_type:
        rc_list.append(
            {
                "RequestedAttribute": {"v": "ProcessType"},
                "RequestedAttributeValue": {"v": f"{process_type}"},
            }
        )

    request = {
        "DocumentIdentification": {"v": "1"},
        "DocumentType": {"v": "A25"},
        "SenderIdentification": {
            "v": f"{sender_id}",
            "codingScheme": f"{sender_coding}",
        },
        "SenderRole": {"v": "A08"},
        "ReceiverIdentification": {"v": " ", "codingScheme": "A01"},
        "ReceiverRole": {"v": "A05"},
        "CreationDateTime": {
            "v": datetime.now(timezone.utc)
            .replace(microsecond=0)
            .strftime("%Y-%m-%dT%H:%M:%SZ")
        },
        "RequestComponent": rc_list,
    }
    return self.client.service.GetData(request=request)

get_px_market_trades(start_time_utc, end_time_utc, time_resolution, px_trader=None, px_trader_scheme='A01', process_type=None, mba=None)

Fetch Power Exchange Market Trades (PXT) data for exchange trading activities.

Retrieves information about trades executed on power exchanges, including trade volumes, prices, and market participant details.

Parameters:

Name	Type	Description	Default
start_time_utc	datetime	Start time in UTC (tz-aware datetime).	required
end_time_utc	datetime	End time in UTC (tz-aware datetime).	required
time_resolution	str	ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.	required
px_trader	Optional[str]	Optional power exchange trader identifier.	None
px_trader_scheme	str	Coding scheme for trader identifier (default "A01").	'A01'
process_type	Optional[str]	Optional process type filter for trade categorization.	None
mba	Optional[str]	Optional Metering Balance Area identifier.	None

Returns:

Type	Description
Any	SOAP response object containing power exchange market trades data.

Raises:

Type	Description
Exception	If SOAP service call fails.
ValueError	If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

Example

from datetime import datetime, timezone
api = SoapApiClient(area="FI")
result = api.get_px_market_trades(
    start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
    end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
    time_resolution="PT1H",
px_trader="TRADER_123",
process_type="A01"
)

Source code in physical_operations_utils/esett_utils/eSettSoapApi.py

def get_px_market_trades(
    self,
    start_time_utc: datetime,
    end_time_utc: datetime,
    time_resolution: str,
    px_trader: Optional[str] = None,
    px_trader_scheme: str = "A01",
    process_type: Optional[str] = None,
    mba: Optional[str] = None,
) -> Any:
    """
    Fetch **Power Exchange Market Trades (PXT)** data for exchange trading activities.

    Retrieves information about trades executed on power exchanges, including
    trade volumes, prices, and market participant details.

    Args:
        start_time_utc: Start time in UTC (tz-aware datetime).
        end_time_utc: End time in UTC (tz-aware datetime).
        time_resolution: ISO 8601 duration string. Must be one of: PT15M, PT30M, PT1H, P1D.
        px_trader: Optional power exchange trader identifier.
        px_trader_scheme: Coding scheme for trader identifier (default `"A01"`).
        process_type: Optional process type filter for trade categorization.
        mba: Optional Metering Balance Area identifier.

    Returns:
        SOAP response object containing power exchange market trades data.

    Raises:
        Exception: If SOAP service call fails.
        ValueError: If datetime parameters are invalid (not UTC, start >= end) or time_resolution is not supported.

    Example:
        ```python
        from datetime import datetime, timezone
        api = SoapApiClient(area="FI")
        result = api.get_px_market_trades(
            start_time_utc=datetime(2025, 5, 1, tzinfo=timezone.utc),
            end_time_utc=datetime(2025, 5, 2, tzinfo=timezone.utc),
            time_resolution="PT1H",
        px_trader="TRADER_123",
        process_type="A01"
        )
        ```
    """
    # Validate input parameters
    self._validate_datetime_parameters(start_time_utc, end_time_utc)
    self._validate_time_resolution(time_resolution)
    sender_coding = self.coding_scheme[self.area]
    sender_id = self.sender_indentification[self.area]
    rc_list = [
        {
            "RequestedAttribute": {"v": "DataFlow"},
            "RequestedAttributeValue": {"v": "PXT"},
        },
        {
            "RequestedAttribute": {"v": "TimeInterval"},
            "RequestedAttributeValue": {
                "v": f"{start_time_utc.isoformat()}Z/{end_time_utc.isoformat()}Z"
            },
        },
        {
            "RequestedAttribute": {"v": "TimeResolution"},
            "RequestedAttributeValue": {"v": f"{time_resolution}"},
        },
    ]
    if px_trader:
        rc_list.append(
            {
                "RequestedAttribute": {"v": "PXTrader"},
                "RequestedAttributeValue": {
                    "v": f"{px_trader}",
                    "codingScheme": f"{px_trader_scheme}",
                },
            }
        )
    if process_type:
        rc_list.append(
            {
                "RequestedAttribute": {"v": "ProcessType"},
                "RequestedAttributeValue": {"v": f"{process_type}"},
            }
        )
    if mba:
        rc_list.append(
            {
                "RequestedAttribute": {"v": "MBA"},
                "RequestedAttributeValue": {"v": f"{mba}", "codingScheme": "A01"},
            }
        )

    request = {
        "DocumentIdentification": {"v": "1"},
        "DocumentType": {"v": "A25"},
        "SenderIdentification": {
            "v": f"{sender_id}",
            "codingScheme": f"{sender_coding}",
        },
        "SenderRole": {"v": "A08"},
        "ReceiverIdentification": {"v": " ", "codingScheme": "A01"},
        "ReceiverRole": {"v": "A05"},
        "CreationDateTime": {
            "v": datetime.now(timezone.utc)
            .replace(microsecond=0)
            .strftime("%Y-%m-%dT%H:%M:%SZ")
        },
        "RequestComponent": rc_list,
    }
    return self.client.service.GetData(request=request)