OpenElectricity Python Client
A Python client for the OpenElectricity API, providing access to electricity and energy network data and metrics for Australia.
To obtain an API key visit platform.openelectricity.org.au
For documentation visit docs.openelectricity.org.au.
See CHANGELOG.md for release notes.
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
# or with uv (recommended)
uv add openelectricity
# Install with data analysis support (Polars/Pandas)
uv add "openelectricity[analysis]"
# Install base package with pip
pip install openelectricity
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
Quick Test
You can test the client and authentication with the following:
Data Examples
Examples of using the client are in the examples directory. Here are some basic examples:
from datetime import datetime, timedelta
from openelectricity import OEClient
from openelectricity.types import DataMetric, UnitFueltechType, UnitStatusType
# 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 operating solar and wind facilities
facilities = client.get_facilities(
network_id=["NEM"],
status_id=[UnitStatusType.OPERATING],
fueltech_id=[UnitFueltechType.SOLAR_UTILITY, UnitFueltechType.WIND],
)
# 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:
# Get operating solar and wind facilities
facilities = await client.get_facilities(
network_id=["NEM"],
status_id=[UnitStatusType.OPERATING],
fueltech_id=[UnitFueltechType.SOLAR_UTILITY, UnitFueltechType.WIND],
)
# Get network data
response = await client.get_network_data(
network_code="NEM",
metrics=[DataMetric.POWER],
interval="1d",
secondary_grouping="fueltech_group",
)
# 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]"
from openelectricity import OEClient
from openelectricity.types import DataMetric
with OEClient() as client:
response = client.get_network_data(
network_code="NEM",
metrics=[DataMetric.POWER, DataMetric.ENERGY],
interval="1d",
secondary_grouping="fueltech_group",
)
# Convert to Polars DataFrame
df = response.to_polars()
# Get metric units
units = response.get_metric_units()
# Analyze data
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
# Make sure you've installed with analysis extras
# uv add "openelectricity[analysis]"
from openelectricity import OEClient
from openelectricity.types import DataMetric
with OEClient() as client:
response = client.get_network_data(
network_code="NEM",
metrics=[DataMetric.POWER, DataMetric.ENERGY],
interval="1d",
secondary_grouping="fueltech_group",
)
# Convert to Pandas DataFrame
df = response.to_pandas()
# Get metric units
units = response.get_metric_units()
# Analyze data
energy_by_fueltech = (
df.groupby("fueltech_group")
.agg({
"energy": "sum",
"power": "mean",
})
.sort_values("energy", ascending=False)
)
Development
Development is preferred with uv and there are targets in the Makefile for common tasks and managing releases. There are optional dependency groups for development, analysis and testing. You can install all of them with make install (which runs uv sync --all-extras).
-
Clone the repository
-
Install development dependencies:
make install -
Run tests:
make test
-
Format code:
make format -
Run linters:
make lint
License
This project is licensed under the MIT License - see the LICENSE file for details.
Metadata
Release files for openelectricity 0.11.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| openelectricity-0.11.3.tar.gz | 251.1 kB | Without provenance | Details for openelectricity-0.11.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| openelectricity-0.11.3-py3-none-any.whl | Python 3 | none | any | Details for openelectricity-0.11.3-py3-none-any.whl |
Total release size: 273.4 kB
Release files / openelectricity-0.11.3.tar.gz
| Download URL | openelectricity-0.11.3.tar.gz |
|---|---|
| Size | 251.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
feda847fceac289421495aa3d98e64db59022b9cff478ab6e02d29fb8f1c1fa3
|
|
BLAKE2b-256 checksum How to use checksums |
3fb4552af7041a350197c76ad3c76c2a691da75234b3c6ce8b97f7676dc28153
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.0
|
Release files / openelectricity-0.11.3-py3-none-any.whl
| Download URL | openelectricity-0.11.3-py3-none-any.whl |
|---|---|
| Size | 22.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9a3d853d264b67bbf2bc5ee67fe1e9f0549d21a8f2a75b8be2a1671550e45d80
|
|
BLAKE2b-256 checksum How to use checksums |
9b30bc82577c251abfec83fa613df3c55813f87561a412c7e05ef72aa43b264c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.0
|
Security for openelectricity 0.11.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.