Skip to main content

KUB

An async Python library for retrieving utility usage data from the Knoxville Utilities Board (KUB) API.

Features

  • Authenticates via Azure AD B2C using PKCE OAuth2, mirroring the KUB web app flow
  • Supports electricity, gas, water, and wastewater services
  • Retrieves hourly usage and cost data for any date range
  • Session management with automatic token refresh
  • Compatible with Home Assistant custom components

Requirements

  • Python 3.12 or higher
  • aiohttp 3.9 or higher

Installation

pip install kub

Usage

Basic setup

import asyncio
from kub import KubUtility

async def main():
    utility = KubUtility("your@email.com", "yourpassword")

    # Retrieve usage for the last 31 days
    usage = await utility.retrieve_last_31_days()
    print(usage)

asyncio.run(main())

Available methods

Method Description
retrieve_last_31_days() Fetches hourly usage for the past 31 days across all services
retrieve_monthly_usage() Fetches hourly usage from the first of the current month to today
retrieve_recent_usage(days=7, start_date=None) Fetches the entire current month plus at least days of overlap; an earlier start_date extends the window for catch-up
retrieve_last_year() Fetches a year of history for backfills or repairs
retrieve_usage_by_range(start_date, end_date) Fetches usage for a custom range; dates are YYYY-MM-DD strings
retrieve_account_info() Fetches account metadata (account ID, person ID, service list) without pulling usage data

Usage data structure

The usage attribute is keyed by service point, then by date, then by time. For an account with one meter for a utility, the service-point key is the utility name (for example, "electricity"). When an account has multiple meters of the same utility, the key is <utility>_<service-point-id> (for example, "electricity_12345"). All accounts on the login are discovered in API order. The first account retains these key rules; additional accounts always use <utility>_<service-point-id>, keeping the first account's keys stable. account_ids lists the accounts and account_people maps them to their owners.

Each usage request replaces the cached snapshot for that service with the requested range. Use retrieve_recent_usage() for polling that includes recent revisions and the whole current month. Its default dates use America/New_York.

{
    "electricity": {
        "2026-05-01": {
            "08:00:00": {
                "id": "...",
                "readDateTime": "2026-05-01T08:00:00",
                "utilityUsed": 0.42,
                "uom": "kWh",
                "cost": 0.06
            },
            ...
        },
        ...
    },
    "gas": { ... },
    "water": { ... },
    "wastewater": { ... }
}

Monthly totals (for the current calendar month) are available via monthly_total:

utility.monthly_total["electricity"]
# {"usage": 312.5, "cost": 42.18}

Totals include only intervals in the current month and year in America/New_York within the fetched range. Hourly timestamps mark the end of the interval, so a midnight reading on the first belongs to the preceding month.

Supported utility types

The KUBUtilityTypes enum represents the services KUB provides:

from kub import KUBUtilityTypes

KUBUtilityTypes.ELECTRICITY
KUBUtilityTypes.GAS
KUBUtilityTypes.WATER
KUBUtilityTypes.WASTEWATER

Only the services active on your account are populated. Check utility.service_list after calling any retrieval method to see the available service-point keys.

Home Assistant

This library is designed to work as a dependency for a Home Assistant custom component. Place the kub directory inside custom_components/ and import from it using standard relative imports.

Development

Install development dependencies:

pip install -e ".[dev]"

Run the test suite:

pytest

License

MIT

Metadata

Release files for kub 0.8.1

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

Source distribution (sdist)

Source distribution for kub 0.8.1
File Size Uploaded Provenance Actions
kub-0.8.1.tar.gz 17.1 kB With provenance Details for kub-0.8.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for kub 0.8.1
File Interpreter ABI Platform Actions
kub-0.8.1-py3-none-any.whl Python 3 none any Details for kub-0.8.1-py3-none-any.whl

Total release size: 29.3 kB

Release files / kub-0.8.1.tar.gz

Download URL kub-0.8.1.tar.gz
Size 17.1 kB
Tags Source
SHA-256 checksum
How to use checksums
8133d0ec8dff11c5e7ff63afe4eb1cf5618d3a33691e2a2e9bd06fa1b937053d
BLAKE2b-256 checksum
How to use checksums
c341b15bc51790fee112457181d0fb18b950137def12b3f7f5f13260600c7dac
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 10, 2026.

Transparency log

Release files / kub-0.8.1-py3-none-any.whl

Download URL kub-0.8.1-py3-none-any.whl
Size 12.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3f6d53fc12d3a8efb323873274258af93c9f3508a4aec881a3883cf7f6d1199f
BLAKE2b-256 checksum
How to use checksums
014ae9a5c11de52cfb28005b7a9437e72872d8aebe7427d2022ac253d2eab9f1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 10, 2026.

Transparency log

Security for kub 0.8.1

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for kub-0.8.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 10, 2026.

Transparency log

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page