python-openei

An asynchronous Python library for consuming utility rate data from the OpenEI.org API and outputting it into an easy-to-use format.

Features

Asynchronous API: Fully built on aiohttp for non-blocking network calls.
Auto Caching: Automatically caches API responses locally (24-hour expiration) to stay within rate limits.
Utility Plan Lookup: Find utility rate plans by coordinates (latitude/longitude) or street address.
Rate Schedule Queries: Calculates current and upcoming energy rates, demand rates, adjustments, and tier/sell rates for any given date and time.

Installation

Install using pip:

pip install python-openei

Quick Start

You will need an API key from OpenEI.org.

Basic Usage

Here is a quick example of how to retrieve and query energy rates for a specific plan:

import asyncio
from openeihttp import Rates

async def main():
    # Initialize Rates helper
    # Retrieve a specific plan (e.g. "539fca56ec12157c50403bf6")
    api = Rates(
        api="YOUR_OPENEI_API_KEY",
        plan="539fca56ec12157c50403bf6",
        cache_file="my_rate_cache.json"  # Optional local cache file
    )

    # Fetch/update the rate plan details
    await api.update()

    print(f"Rate Plan Name: {api.rate_name}")
    print(f"Current Energy Rate: ${api.current_rate}/kWh")
    print(f"Current Sell Rate: ${api.current_sell_rate}/kWh")

    # Check what the next rate will be and when it changes
    next_time = api.next_energy_rate_structure_time
    next_rate = api.next_energy_rate_structure
    print(f"Next rate change at: {next_time} (structure ID: {next_rate})")

asyncio.run(main())

Plan Lookup

If you do not know the plan ID, you can look up available plans using a latitude/longitude pair or a physical address:

import asyncio
from openeihttp import Rates

async def lookup():
    # Set up lookup using latitude and longitude
    api = Rates(
        api="YOUR_OPENEI_API_KEY",
        lat=37.7749,
        lon=-122.4194,
        radius=5.0  # Optional search radius in miles
    )

    plans = await api.lookup_plans()

    # plans will be grouped by utility name
    for utility, plan_list in plans.items():
        print(f"\nUtility: {utility}")
        for plan in plan_list:
            print(f"  - {plan['name']} (Plan Label: {plan['label']})")

asyncio.run(lookup())

API Reference

Properties

The Rates object exposes the following properties after a successful update():

Property	Return Type	Description
`rate_name`	`str`	Name of the utility rate plan.
`approval`	`bool`	Approval status of the rate plan on OpenEI.
`current_rate`	`float \| None`	Current active energy rate in $/kWh.
`current_sell_rate`	`float \| None`	Current net-metering / sell rate in $/kWh.
`current_adjustment`	`float \| None`	Current rate adjustment value in $/kWh.
`next_energy_rate_structure`	`int \| None`	Upcoming energy rate structure ID.
`next_energy_rate_structure_time`	`datetime \| None`	The time at which the next energy rate structure starts.
`current_demand_rate`	`float \| None`	Current demand rate.
`current_demand_adjustment`	`float \| None`	Current demand rate adjustment.
`demand_unit`	`str \| None`	The unit of the demand rate.
`monthly_tier_rate`	`float \| None`	Current tier rate based on monthly meter reading.
`distributed_generation`	`str \| None`	Distributed generation rules / net-metering type.
`mincharge`	`tuple[float, str] \| None`	Minimum charge amount and units (e.g. `(10.0, "$/month")`).
`fixedchargefirstmeter`	`tuple[float, str] \| None`	Fixed charge amount and units for the first meter.

Methods

await api.update(): Updates the internal data. Loads from cache if fresh, otherwise fetches from API and caches locally.
await api.update_data(): Forces a fresh API call (bypassing cache) and rewrites the cache file.
await api.clear_cache(): Deletes the cache file if one was configured.
api.rate(date: datetime): Look up the energy rate for a specific date and time.
api.sell_rate(date: datetime): Look up the sell/net-metering rate for a specific date and time.
api.demand_rate(date: datetime): Look up the demand rate for a specific date and time.

Development

This project uses tox to run checks and tests across Python versions.

Run Tests and Linters

Make sure you have tox installed, then run:

tox

Metadata

Release files for python-openei 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for python-openei 0.3.0
File	Size	Uploaded
python_openei-0.3.0.tar.gz	19.2 kB	May 22, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for python-openei 0.3.0
File	Interpreter	ABI	Platform	Reset
python_openei-0.3.0-py3-none-any.whl 13.1 kB May 22, 2026	Python 3	none	any	Details

Total release size: 32.3 kB

Release files / python_openei-0.3.0.tar.gz

Download URL	python_openei-0.3.0.tar.gz
Size	19.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`655c51366732993fe9420c3d6a2ed982b0bc1816bbddfd7ed2ef810a619847eb`
BLAKE2b-256 checksum How to use checksums	`adee98158871b1db6ef749f4f67348a98d988125b8b76d37fc7b1560bd7b8e9a`
Upload date	May 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.13`

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.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/firstof9/python-openei
Publishing commit: github.com/firstof9/python-openei/tree/b00629aeeeae9b9fd5bea313e7ef130ce4aa6327

Workflow

Publishing configuration: github.com/firstof9/python-openei/blob/b00629aeeeae9b9fd5bea313e7ef130ce4aa6327/.github/workflows/publish-to-pypi.yml
Publishing logs: github.com/firstof9/python-openei/actions/runs/26301918942/attempts/1

Artifact

Subject: python_openei-0.3.0.tar.gz
SHA-256 checksum: 655c51366732993fe9420c3d6a2ed982b0bc1816bbddfd7ed2ef810a619847eb Verifying attestations

Release files / python_openei-0.3.0-py3-none-any.whl

Download URL	python_openei-0.3.0-py3-none-any.whl
Size	13.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`c7aa7e0367840f46351a34fabd8c0be00bf0c355630d3201de7d97104bf1836f`
BLAKE2b-256 checksum How to use checksums	`8cd5a2da734f85c5a3ba917fa8c4da748e6056a21df1463db8f63e89f7bba1a6`
Upload date	May 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.13`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/firstof9/python-openei
Publishing commit: github.com/firstof9/python-openei/tree/b00629aeeeae9b9fd5bea313e7ef130ce4aa6327

Workflow

Publishing configuration: github.com/firstof9/python-openei/blob/b00629aeeeae9b9fd5bea313e7ef130ce4aa6327/.github/workflows/publish-to-pypi.yml
Publishing logs: github.com/firstof9/python-openei/actions/runs/26301918942/attempts/1

Artifact

Subject: python_openei-0.3.0-py3-none-any.whl
SHA-256 checksum: c7aa7e0367840f46351a34fabd8c0be00bf0c355630d3201de7d97104bf1836f Verifying attestations