Models API Reference

This page documents the data models used for API responses.

Response Models

APIResponse

Bases: BaseModel

Generic API response wrapper.

Most BMRS API endpoints return data in this format.

Source code in elexon_bmrs/models.py

class APIResponse(BaseModel):
    """
    Generic API response wrapper.

    Most BMRS API endpoints return data in this format.
    """
    model_config = ConfigDict(extra='allow')

    data: List[Dict[str, Any]] = Field(default_factory=list)
    metadata: Optional[Dict[str, Any]] = None
    total_records: Optional[int] = Field(default=None, alias="totalRecords")

TypedAPIResponse

Bases: BaseModel, Generic[T]

Generic typed API response wrapper.

Use this for type-safe responses

response: TypedAPIResponse[DemandOutturn] = client.get_demand_typed(...)

Source code in elexon_bmrs/models.py

class TypedAPIResponse(BaseModel, Generic[T]):
    """
    Generic typed API response wrapper.

    Use this for type-safe responses:
        response: TypedAPIResponse[DemandOutturn] = client.get_demand_typed(...)
    """
    model_config = ConfigDict(extra='allow')

    data: List[T] = Field(default_factory=list)
    metadata: Optional[Dict[str, Any]] = None
    total_records: Optional[int] = Field(default=None, alias="totalRecords")

Specific Response Types

SystemDemandResponse

Bases: TypedAPIResponse['DemandData']

Typed response for system demand endpoints.

Example

response = client.get_system_demand(...) for demand in response.data: print(f"{demand.settlement_date}: {demand.demand} MW")

Source code in elexon_bmrs/models.py

class SystemDemandResponse(TypedAPIResponse["DemandData"]):
    """
    Typed response for system demand endpoints.

    Example:
        >>> response = client.get_system_demand(...)
        >>> for demand in response.data:
        >>>     print(f"{demand.settlement_date}: {demand.demand} MW")
    """
    pass

GenerationResponse

Bases: TypedAPIResponse[GenerationByFuelType]

Typed response for generation by fuel type endpoints.

Source code in elexon_bmrs/models.py

class GenerationResponse(TypedAPIResponse[GenerationByFuelType]):
    """Typed response for generation by fuel type endpoints."""
    pass

WindForecastResponse

Bases: TypedAPIResponse['WindGenerationForecast']

Typed response for wind generation forecast endpoints.

Source code in elexon_bmrs/models.py

class WindForecastResponse(TypedAPIResponse["WindGenerationForecast"]):
    """Typed response for wind generation forecast endpoints."""
    pass

SystemPricesResponse

Bases: TypedAPIResponse[MarketIndex]

Typed response for system prices endpoints.

Source code in elexon_bmrs/models.py

class SystemPricesResponse(TypedAPIResponse[MarketIndex]):
    """Typed response for system prices endpoints."""
    pass

SystemFrequencyResponse

Bases: TypedAPIResponse[SystemFrequency]

Typed response for system frequency endpoints.

Source code in elexon_bmrs/models.py

class SystemFrequencyResponse(TypedAPIResponse[SystemFrequency]):
    """Typed response for system frequency endpoints."""
    pass

ImbalancePricesResponse

Bases: TypedAPIResponse[ImbalancePrice]

Typed response for imbalance prices endpoints.

Source code in elexon_bmrs/models.py

class ImbalancePricesResponse(TypedAPIResponse[ImbalancePrice]):
    """Typed response for imbalance prices endpoints."""
    pass

Data Models

DemandData

Bases: BaseModel

Model for electricity demand data.

Source code in elexon_bmrs/models.py

class DemandData(BaseModel):
    """Model for electricity demand data."""
    model_config = ConfigDict(extra='allow')

    settlement_date: str = Field(alias="settlementDate")
    settlement_period: int = Field(alias="settlementPeriod")
    timestamp: Optional[datetime] = None
    demand: float  # in MW

GenerationByFuelType

Bases: BaseModel

Model for generation by fuel type data.

Source code in elexon_bmrs/models.py

class GenerationByFuelType(BaseModel):
    """Model for generation by fuel type data."""
    model_config = ConfigDict(extra='allow')

    settlement_date: str = Field(alias="settlementDate")
    settlement_period: int = Field(alias="settlementPeriod")
    ccgt: Optional[float] = None  # Combined Cycle Gas Turbine
    oil: Optional[float] = None
    coal: Optional[float] = None
    nuclear: Optional[float] = None
    wind: Optional[float] = None
    ps: Optional[float] = None  # Pumped Storage
    npshyd: Optional[float] = None  # Non-Pumped Storage Hydro
    ocgt: Optional[float] = None  # Open Cycle Gas Turbine
    other: Optional[float] = None
    intfr: Optional[float] = None  # Interconnector France
    intirl: Optional[float] = None  # Interconnector Ireland
    intned: Optional[float] = None  # Interconnector Netherlands
    intew: Optional[float] = None  # East-West Interconnector
    biomass: Optional[float] = None

SystemFrequency

Bases: BaseModel

Model for system frequency data.

Source code in elexon_bmrs/models.py

class SystemFrequency(BaseModel):
    """Model for system frequency data."""
    model_config = ConfigDict(extra='allow')

    timestamp: datetime
    frequency: float

MarketIndex

Bases: BaseModel

Model for market index data.

Source code in elexon_bmrs/models.py

class MarketIndex(BaseModel):
    """Model for market index data."""
    model_config = ConfigDict(extra='allow')

    settlement_date: str = Field(alias="settlementDate")
    settlement_period: int = Field(alias="settlementPeriod")
    price: float

ImbalancePrice

Bases: BaseModel

Model for imbalance pricing data.

Source code in elexon_bmrs/models.py

class ImbalancePrice(BaseModel):
    """Model for imbalance pricing data."""
    model_config = ConfigDict(extra='allow')

    settlement_date: str = Field(alias="settlementDate")
    settlement_period: int = Field(alias="settlementPeriod")
    imbalance_price_gbp_per_mwh: float = Field(alias="imbalancePriceGbpPerMwh")

SettlementPeriod

Bases: BaseModel

Model for settlement period data.

Source code in elexon_bmrs/models.py

class SettlementPeriod(BaseModel):
    """Model for settlement period data."""
    model_config = ConfigDict(extra='allow')

    settlement_date: str = Field(alias="settlementDate")
    settlement_period: int = Field(alias="settlementPeriod")
    start_time: Optional[datetime] = Field(default=None, alias="startTime")
    end_time: Optional[datetime] = Field(default=None, alias="endTime")