Electric Meter

CPAU Electric Meter Implementation

This module provides the CpauElectricMeter class for retrieving electric meter usage data from the CPAU portal.

class cpau.electric_meter.CpauElectricMeter(session, meter_info)

Bases: CpauMeter

Represents a CPAU electric meter and provides methods to retrieve usage data.

Supports five interval types: - billing: Billing period data (CPAU’s billing periods, roughly monthly) - monthly: Calendar month aggregation (sum of daily data by month) - daily: Daily aggregated usage - hourly: Hourly usage data - 15min: 15-minute interval usage data

get_available_intervals()

Get list of supported interval types for electric meters.

Return type:

list[str]

Returns:

[‘billing’, ‘monthly’, ‘daily’, ‘hourly’, ‘15min’]

property rate_category: str

Get the rate category/schedule for this meter.

get_usage(interval, start_date, end_date=None)

Retrieve usage data for the specified interval and date range.

Parameters:

• interval (str) – One of ‘billing’, ‘monthly’, ‘daily’, ‘hourly’, ‘15min’

• start_date (date) – Start date (inclusive)

• end_date (Optional[date]) – End date (inclusive). If None, defaults to 2 days ago.

Return type:

list[UsageRecord]

Returns:

List of UsageRecord objects sorted by date

Raises:

• ValueError – If interval is invalid or date range is invalid

• CpauApiError – If API request fails

Notes

• billing: Returns CPAU billing periods that overlap with the date range

• monthly: Returns calendar month aggregations of daily data

• Other intervals return data within the exact date range

• Date range is limited to data available from CPAU (typically not within last 2 days)

get_billing_usage(start_date, end_date=None)

Retrieve billing period data.

Convenience method equivalent to get_usage(interval=’billing’, …)

Return type:

list[UsageRecord]

Returns:

List of UsageRecord objects with billing_period attribute populated

get_monthly_usage(start_date, end_date=None)

Retrieve calendar month aggregated usage data.

Convenience method equivalent to get_usage(interval=’monthly’, …) Aggregates daily data into calendar months.

Return type:

list[UsageRecord]

Returns:

List of UsageRecord objects, one per calendar month

get_daily_usage(start_date, end_date=None)

Retrieve daily usage data.

Convenience method equivalent to get_usage(interval=’daily’, …)

Return type:

list[UsageRecord]

get_hourly_usage(start_date, end_date=None)

Retrieve hourly usage data.

Convenience method equivalent to get_usage(interval=’hourly’, …)

Note: For large date ranges, this makes one API call per day and may be slow.

Return type:

list[UsageRecord]

get_15min_usage(start_date, end_date=None)

Retrieve 15-minute interval usage data.

Convenience method equivalent to get_usage(interval=’15min’, …)

Note: For large date ranges, this makes one API call per day and may be slow.

Return type:

list[UsageRecord]

get_availability_window(interval)

Find the earliest and latest dates for which data is available.

Uses binary search for efficiency (typically 10-15 API calls per boundary).

Parameters:

interval (str) – One of ‘billing’, ‘monthly’, ‘daily’, ‘hourly’, ‘15min’

Return type:

tuple[Optional[date], Optional[date]]

Returns:

Tuple of (earliest_date, latest_date) or (None, None) if no data found

Notes

• For ‘billing’: Scans all billing periods (single API call)

• For ‘monthly’: Returns the daily data availability window (since monthly aggregates daily data)

• For other intervals: Uses binary search (10-15 API calls per boundary)

• Total execution time: typically 30-60 seconds for intervals requiring binary search

Raises:

ValueError – If interval is invalid

iter_usage(interval, start_date, end_date=None, chunk_days=30)

Iterate over usage data in chunks to avoid loading large datasets into memory.

Parameters:

• interval (str) – One of ‘billing’, ‘monthly’, ‘daily’, ‘hourly’, ‘15min’

• start_date (date) – Start date (inclusive)

• end_date (Optional[date]) – End date (inclusive). If None, defaults to 2 days ago.

• chunk_days (int) – Number of days to fetch per API request (default 30)

Yields:

UsageRecord objects one at a time

Return type:

Iterator[UsageRecord]

Notes

• Useful for processing large date ranges without loading all data into memory

• Billing and monthly intervals don’t benefit from chunking (billing returns all periods, monthly aggregates daily data)

CpauElectricMeter

class cpau.electric_meter.CpauElectricMeter(session, meter_info)

Bases: CpauMeter

Represents a CPAU electric meter and provides methods to retrieve usage data.

Supports five interval types: - billing: Billing period data (CPAU’s billing periods, roughly monthly) - monthly: Calendar month aggregation (sum of daily data by month) - daily: Daily aggregated usage - hourly: Hourly usage data - 15min: 15-minute interval usage data

Supported Intervals

• billing - Billing period data (CPAU’s billing periods)

• monthly - Calendar month aggregation (sum of daily data by month)

• daily - Daily aggregated usage

• hourly - Hourly usage data

• 15min - 15-minute interval usage data

Example

from cpau import CpauApiSession
from datetime import date

with CpauApiSession(userid='user@example.com', password='password') as session:
    meter = session.get_electric_meter()

    # Get daily usage data
    records = meter.get_usage(
        interval='daily',
        start_date=date(2024, 12, 1),
        end_date=date(2024, 12, 31)
    )

    # Process records
    for record in records:
        print(f"{record.date}: {record.net_kwh} kWh")

    # Check data availability
    earliest, latest = meter.get_availability_window('daily')
    print(f"Data available from {earliest} to {latest}")

get_available_intervals()

Get list of supported interval types for electric meters.

Return type:

list[str]

Returns:

[‘billing’, ‘monthly’, ‘daily’, ‘hourly’, ‘15min’]

property rate_category: str

Get the rate category/schedule for this meter.

get_usage(interval, start_date, end_date=None)

Retrieve usage data for the specified interval and date range.

Parameters:

• interval (str) – One of ‘billing’, ‘monthly’, ‘daily’, ‘hourly’, ‘15min’

• start_date (date) – Start date (inclusive)

• end_date (Optional[date]) – End date (inclusive). If None, defaults to 2 days ago.

Return type:

list[UsageRecord]

Returns:

List of UsageRecord objects sorted by date

Raises:

• ValueError – If interval is invalid or date range is invalid

• CpauApiError – If API request fails

Notes

• billing: Returns CPAU billing periods that overlap with the date range

• monthly: Returns calendar month aggregations of daily data

• Other intervals return data within the exact date range

• Date range is limited to data available from CPAU (typically not within last 2 days)

get_billing_usage(start_date, end_date=None)

Retrieve billing period data.

Convenience method equivalent to get_usage(interval=’billing’, …)

Return type:

list[UsageRecord]

Returns:

List of UsageRecord objects with billing_period attribute populated

get_monthly_usage(start_date, end_date=None)

Retrieve calendar month aggregated usage data.

Convenience method equivalent to get_usage(interval=’monthly’, …) Aggregates daily data into calendar months.

Return type:

list[UsageRecord]

Returns:

List of UsageRecord objects, one per calendar month

get_daily_usage(start_date, end_date=None)

Retrieve daily usage data.

Convenience method equivalent to get_usage(interval=’daily’, …)

Return type:

list[UsageRecord]

get_hourly_usage(start_date, end_date=None)

Retrieve hourly usage data.

Convenience method equivalent to get_usage(interval=’hourly’, …)

Note: For large date ranges, this makes one API call per day and may be slow.

Return type:

list[UsageRecord]

get_15min_usage(start_date, end_date=None)

Retrieve 15-minute interval usage data.

Convenience method equivalent to get_usage(interval=’15min’, …)

Note: For large date ranges, this makes one API call per day and may be slow.

Return type:

list[UsageRecord]

get_availability_window(interval)

Find the earliest and latest dates for which data is available.

Uses binary search for efficiency (typically 10-15 API calls per boundary).

Parameters:

interval (str) – One of ‘billing’, ‘monthly’, ‘daily’, ‘hourly’, ‘15min’

Return type:

tuple[Optional[date], Optional[date]]

Returns:

Tuple of (earliest_date, latest_date) or (None, None) if no data found

Notes

• For ‘billing’: Scans all billing periods (single API call)

• For ‘monthly’: Returns the daily data availability window (since monthly aggregates daily data)

• For other intervals: Uses binary search (10-15 API calls per boundary)

• Total execution time: typically 30-60 seconds for intervals requiring binary search

Raises:

ValueError – If interval is invalid

iter_usage(interval, start_date, end_date=None, chunk_days=30)

Iterate over usage data in chunks to avoid loading large datasets into memory.

Parameters:

• interval (str) – One of ‘billing’, ‘monthly’, ‘daily’, ‘hourly’, ‘15min’

• start_date (date) – Start date (inclusive)

• end_date (Optional[date]) – End date (inclusive). If None, defaults to 2 days ago.

• chunk_days (int) – Number of days to fetch per API request (default 30)

Yields:

UsageRecord objects one at a time

Return type:

Iterator[UsageRecord]

Notes

• Useful for processing large date ranges without loading all data into memory

• Billing and monthly intervals don’t benefit from chunking (billing returns all periods, monthly aggregates daily data)

__init__(session, meter_info)

Initialize a meter object.

Parameters:

• session (CpauApiSession) – Authenticated CpauApiSession

• meter_info (dict) – Dictionary containing meter details from API

Note: This should only be called by CpauApiSession factory methods,

not directly by library consumers.

__repr__()

String representation of the meter.

Return type:

str

property address: str

Get the service address for this meter.

property meter_number: str

Get the meter number/identifier.

property meter_type: str

Get the meter type (‘E’ for electric, ‘W’ for water).

property status: int

Get the meter status (1 = active).

UsageRecord

class cpau.meter.UsageRecord(date, import_kwh, export_kwh, net_kwh, billing_period_start=None, billing_period_end=None, billing_period_length=None)

Represents a single usage data point.

date

Date (or datetime for hourly/15min) of the reading

import_kwh

Energy imported from grid (consumption)

export_kwh

Energy exported to grid (solar generation)

net_kwh

Net energy (import - export)

billing_period_start

Optional start date of billing period (billing interval only)

billing_period_end

Optional end date of billing period (billing interval only)

billing_period_length

Optional length of billing period in days (billing interval only)

Fields

• date (date or datetime): Timestamp for this record

• export_kwh (float): Solar generation sent to grid (for NEM 2.0 customers)

• import_kwh (float): Electricity consumed from grid

• net_kwh (float): Import - Export (positive = net consumption)

• billing_period_start (str, optional): Start of billing period (billing interval only)

• billing_period_end (str, optional): End of billing period (billing interval only)

• billing_period_length (int, optional): Days in billing period (billing interval only)

date: datetime

import_kwh: float

export_kwh: float

net_kwh: float

billing_period_start: str | None = None

billing_period_end: str | None = None

billing_period_length: int | None = None

__init__(date, import_kwh, export_kwh, net_kwh, billing_period_start=None, billing_period_end=None, billing_period_length=None)