python-openei

PyPI version License: MIT

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

Project links

Data verified by PyPI on May 22, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for firstof9 from gravatar.com firstof9

Credits

Author: firstof9

GitHub Statistics

Data verified by PyPI on May 22, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

Requires

Python >=3.8

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

python_openei-0.3.0.tar.gz (19.2 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

python_openei-0.3.0-py3-none-any.whl (13.1 kB view details)

Uploaded Python 3

File details

Details for the file python_openei-0.3.0.tar.gz.

File metadata

  • Download URL: python_openei-0.3.0.tar.gz
  • Upload date:
  • Size: 19.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for python_openei-0.3.0.tar.gz
Algorithm Hash digest
SHA256 655c51366732993fe9420c3d6a2ed982b0bc1816bbddfd7ed2ef810a619847eb
MD5 addae005e6746c3e0e3a312083a36390
BLAKE2b-256 adee98158871b1db6ef749f4f67348a98d988125b8b76d37fc7b1560bd7b8e9a

See more details on using hashes here.

Provenance

The following attestation bundles were made for python_openei-0.3.0.tar.gz:

Publisher: publish-to-pypi.yml on firstof9/python-openei

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file python_openei-0.3.0-py3-none-any.whl.

File metadata

  • Download URL: python_openei-0.3.0-py3-none-any.whl
  • Upload date:
  • Size: 13.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for python_openei-0.3.0-py3-none-any.whl
Algorithm Hash digest
SHA256 c7aa7e0367840f46351a34fabd8c0be00bf0c355630d3201de7d97104bf1836f
MD5 4359d9ef5ccd6e5bf0a19e5863a7cdbc
BLAKE2b-256 8cd5a2da734f85c5a3ba917fa8c4da748e6056a21df1463db8f63e89f7bba1a6

See more details on using hashes here.

Provenance

The following attestation bundles were made for python_openei-0.3.0-py3-none-any.whl:

Publisher: publish-to-pypi.yml on firstof9/python-openei

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.3.0 This release

2 files

0.2.8

2 files

0.2.7

2 files

0.2.6

2 files

0.2.5

2 files

0.2.4

2 files

0.2.3

2 files

0.2.2

2 files

0.2.1

2 files

0.2.0

2 files

0.1.24

2 files

0.1.23

2 files

0.1.22

2 files

0.1.21

2 files

0.1.20

2 files

0.1.19

2 files

0.1.18

2 files

0.1.17

2 files

0.1.16

2 files

0.1.15

2 files

0.1.14

2 files

0.1.13

2 files

0.1.12

2 files

0.1.11

2 files

0.1.10

2 files

0.1.9

2 files

0.1.8

2 files

0.1.7

2 files

0.1.6

2 files

0.1.5

2 files

0.1.4

2 files

0.1.3

2 files

0.1.1

2 files

0.1.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page