openelectricity 0.2.1

OpenElectricity Python Client

OpenElectricity Python Client

[!WARNING] This project and the v4 API are currently under active development.

A Python client for the OpenElectricity API, providing access to electricity and energy network data and metrics for Australia.

[!NOTE] API key signups are currently waitlisted and will be released gradually.

To obtain an API key visit platform.openelectricity.org.au

For documentation visit docs.openelectricity.org.au

Features

• Synchronous and asynchronous API clients
• Fully typed with comprehensive type annotations
• Automatic request retries and error handling
• Context manager support
• Modern Python (3.10+) with full type annotations
• Direct conversion to Pandas and Polars DataFrames

Installation

# Install base package
pip install openelectricity

# or with uv (recommended)
uv add openelectricity

# Install with data analysis support (Polars/Pandas)
uv add "openelectricity[analysis]"

Quick Start

First, set your API key in the environment:

# Set your API key
export OPENELECTRICITY_API_KEY=your-api-key

# Optional: Override API server (defaults to production)
export OPENELECTRICITY_API_URL=http://localhost:8000/v4

Then in your code:

from datetime import datetime, timedelta
from openelectricity import OEClient
from openelectricity.types import DataMetric

# Calculate date range
end_date = datetime.now().replace(hour=0, minute=0, second=0, microsecond=0)
start_date = end_date - timedelta(days=7)

# Using context manager (recommended)
with OEClient() as client:
    # Get network data for NEM
    response = client.get_network_data(
        network_code="NEM",
        metrics=[DataMetric.POWER, DataMetric.ENERGY],
        interval="1d",
        date_start=start_date,
        date_end=end_date,
        secondary_grouping="fueltech_group",
    )

    # Print results
    for series in response.data:
        print(f"\nMetric: {series.metric}")
        print(f"Unit: {series.unit}")

        for result in series.results:
            print(f"\n  {result.name}:")
            print(f"  Fuel Tech Group: {result.columns.fueltech_group}")
            for point in result.data:
                print(f"    {point.timestamp}: {point.value:.2f} {series.unit}")

For async usage:

from openelectricity import AsyncOEClient
import asyncio

async def main():
    async with AsyncOEClient() as client:
        # by default gets the last 3 days of data
        response = await client.get_network_data(
            network_code="NEM",
            metrics=[DataMetric.POWER],
            interval="1d",
        )
        # Process response...

asyncio.run(main())

Data Analysis

The client provides built-in support for converting API responses to popular data analysis formats.

Using with Polars

# Make sure you've installed with analysis extras
# uv add "openelectricity[analysis]"

with OEClient() as client:
    response = client.get_network_data(
        network_code="NEM",
        metrics=[DataMetric.POWER, DataMetric.ENERGY],
        interval="1d",
        secondary_grouping="fueltech_group",
    )

    # Convert directly to Polars DataFrame
    df = response.to_polars()

    # Get metric units for reference
    units = response.get_metric_units()

    # Example analysis
    energy_by_fueltech = (
        df.group_by("fueltech_group")
        .agg(
            pl.col("energy").sum().alias("total_energy_mwh"),
            pl.col("power").mean().alias("avg_power_mw"),
        )
        .sort("total_energy_mwh", descending=True)
    )

Using with Pandas

# Convert directly to Pandas DataFrame
df = response.to_pandas()

# Example analysis
daily_totals = (
    df.groupby("interval")
    .agg({
        "energy": "sum",
        "power": "sum"
    })
    .sort_index()
)

Development

1. Clone the repository

2. Install development dependencies:

   make install
   

3. Run tests:

   make test
   

4. Format code:

   make format
   

5. Run linters:

   make lint
   

License

This project is licensed under the MIT License - see the LICENSE file for details.