Python SDK

pip install energyoracle

# Or with optional dependencies
pip install energyoracle[pandas]   # Include pandas support
pip install energyoracle[async]    # Include async support
pip install energyoracle[all]      # Include everything

from energyoracle import EnergyOracle

# Initialize client
oracle = EnergyOracle(api_key="your-api-key")

# Get latest UK system price
price = oracle.uk.prices.latest()
print(f"Current price: £{price.value}/MWh")

# Get carbon intensity
carbon = oracle.uk.carbon.current()
print(f"Carbon: {carbon.intensity} gCO2/kWh")

import asyncio
from energyoracle import AsyncEnergyOracle

async def main():
    async with AsyncEnergyOracle(api_key="your-api-key") as oracle:
        # Concurrent requests
        price, carbon = await asyncio.gather(
            oracle.uk.prices.latest(),
            oracle.uk.carbon.current()
        )
        print(f"Price: £{price.value}/MWh")
        print(f"Carbon: {carbon.intensity} gCO2/kWh")

asyncio.run(main())

import pandas as pd
from energyoracle import EnergyOracle

oracle = EnergyOracle(api_key="your-api-key")

# Get price range and convert to DataFrame
prices = oracle.uk.prices.range("2024-12-01", "2024-12-20")
df = prices.to_dataframe()

# DataFrame with columns: settlement_date, period, price, ssp, sbp
print(df.head())

# Quick analysis
print(f"Average price: £{df['price'].mean():.2f}/MWh")
print(f"Peak price: £{df['price'].max():.2f}/MWh")

# Group by date
daily_avg = df.groupby('settlement_date')['price'].mean()

# Merge with carbon data
carbon = oracle.uk.carbon.range("2024-12-01", "2024-12-20")
carbon_df = carbon.to_dataframe()

merged = pd.merge(df, carbon_df, on=['settlement_date', 'period'])

# CLI is included with the package
$ energyoracle --help

# Get latest price
$ energyoracle prices latest
Current UK System Price: £52.34/MWh
Settlement Date: 2024-12-20
Settlement Period: 28

# Get carbon intensity
$ energyoracle carbon current
Carbon Intensity: 142 gCO2/kWh
Index: moderate

# Export to CSV
$ energyoracle prices range --from 2024-12-01 --to 2024-12-20 --output prices.csv

# Calculate capture price
$ energyoracle analytics capture-price --technology wind --year 2024 --month 12

from energyoracle import EnergyOracle
from energyoracle.types import (
    SystemPrice,
    CarbonIntensity,
    FuelMix,
    GreenPremium,
    CapturePrice,
)

oracle = EnergyOracle(api_key="your-api-key")

# All methods have full type hints
price: SystemPrice = oracle.uk.prices.latest()
carbon: CarbonIntensity = oracle.uk.carbon.current()

# IDE autocompletion works out of the box
print(price.settlement_date)
print(carbon.intensity)

from energyoracle import EnergyOracle
from energyoracle.exceptions import (
    OracleError,
    RateLimitError,
    AuthenticationError,
)

oracle = EnergyOracle(api_key="your-api-key")

try:
    price = oracle.uk.prices.latest()
except RateLimitError as e:
    print(f"Rate limited. Retry after: {e.retry_after}s")
except AuthenticationError:
    print("Invalid API key")
except OracleError as e:
    print(f"API Error: {e.message} (status: {e.status})")

# Configure automatic retry
oracle = EnergyOracle(
    api_key="your-api-key",
    retries=3,
    retry_delay=1.0,  # Exponential backoff starting at 1s
)