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

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").

{
    "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}

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