Meter Blocks

To organize utility data for a meter, we split data up into smaller objects called "blocks" and include only the blocks which are relevant to that meter. Separating information like this makes it easier to get started with a simple integration that only deals with basic information and extend it later as needed.

If a block is present for a given meter, it appears under the attribute corresponding to its type name documented here. The type names of all blocks available for a given meter are also listed in the blocks attribute on the meter object.


We have several universal blocks that we support across all utilities. We also have utility-specific blocks to include additional data that doesn't fit into any universal block. We document the attributes in each block type so that you know what you're getting when you parse a block.

Type Name Format Description
base Base Meter Block Basic information about the meter.
electric_details Electric Details Block Information about the electric service provided to this meter, for example the service voltage.
programs Enrolled Programs Information about programs the service is enrolled in.
suppliers Suppliers Block Information about any third party or CCA suppliers this meter has. The information in this block is usually drawn from the latest bill so it may change over time if the account holder changes suppliers.
 Extensible: We may add blocks in the future, so be able to handle unknown attributes gracefully.

Coming soon!

Some utilities require data to be loaded dynamically from their systems every time an API request is made. To minimize the requests made to their systems, we do not load some Meter blocks by default. Instead, we require users to explicitly request fully populated (or "expanded") Meter blocks via the expand_meter_blocks GET parameter. You can tell a Meter needs to be expanded when is_expanded is false in the Meter object.

The following utilities do not expand Meter blocks by default:


The Base Meter Block contains some basic information about the utility service.

For utilities with non-expanded meter blocks by default, Base Meter Block may not include all the attributes. Please use the expand_meter_blocks GET parameter to include all the attributes.

Attribute Format Description Example Utility Gotchas
service_identifier String The utility service agreement id (e.g. SAID). "3-000-1111-22"
service_tariff String The utility tariff name. These are taken straight from the raw source, so you may see multiple representations for the same tariff. "E19"
service_class ServiceClassType The class of utility service. This is usually derived from the meter's tariff. "res-electric"
service_address String The address listed for the utility service. This is what the utility provides, and may not be a full address. "123 MAIN ST"
meter_numbers List(String) A list of the meter numbers for this Meter. There can be zero, one, or multiple meter numbers since a utility service may bundle specific meters into one service, or have a unmetered service. ["10-000-00001", "X90009"]
billing_contact String Who is currently listed as the entity who pays the bills. "123 MAIN ST"
billing_address String Where the bills are sent. This is what the utility provides, and may not be a full address. "123 MAIN ST"
billing_account String The utility billing account id. "2-000-1111-22"
 Extensible: We may extend this object type in the future, so be able to handle unknown attributes gracefully.
// Base Meter Block example
{
    "is_expanded": true,
    "service_identifier": "1234222222-9",
    "service_tariff": "A6X",
    "service_class": "comm-electric",
    "service_address": "222 Broadway St, Suite 100",
    "meter_numbers": ["111.00222.333.002"],
    "billing_contact": "Acme Inc.",
    "billing_address": "222 Broadway St, Suite 100",
    "billing_account": "3456222222-9"
}

This String type is a basic classification for a particular tariff. It may not always correspond well with how the utility classifies services.

Value Description
res-electric Residential electric service.
comm-electric Commercial electric service, including agricultural.
electric Electric service. We don't know whether it is residential or commercial.
res-gas Residential gas service.
comm-gas Commercial gas service, including agricultural.
gas Gas service. We don't know whether it is residential or commercial.
res-water Residential water service.
comm-water Commercial water service.
water Water service. We don't know whether it is residential or commercial.
other Some other service class.
unknown The meter has a tariff we haven't categorized, or we can't classify the meter for some other reason.
 Extensible: We may add variants to this enumeration type in the future, so be able to handle unknown values gracefully.

This block contains information about the electric service provided to a meter.

Attribute Format Description Example
voltage Float The supply voltage at this meter. 120.0
 Extensible: We may extend this object type in the future, so be able to handle unknown attributes gracefully.
// Electric Details Block example
{
    "voltage": 480.0
}

This block contains information about any third party suppliers for this meter. The type of the block is array of Supplier Info, one object for each supplier.

// Suppliers Block example
[
    {
        "supplier_name": "Anytown Community Energy",
        "supplier_service_id": "9812251211",
        "supplier_tariff": "Sunshine A1",
        "supplier_type": "cca"
    }
]

Basic information about a third-party supplier or CCA.

Attribute Format Description Example
supplier_name String The name of the supplier. "Clean Energy Supply LLC"
supplier_service_id String or null The identifier the supplier uses for this meter. "44129-1137"
supplier_tariff String or null The name of the supplier's tariff for this meter. "Large GS"
supplier_type SupplierType The type of supplier: third party, CCA, etc. "direct_access"

Information about special programs the service is currently enrolled in, as of the latest billing information collected. The type of the block is array of Program.

This block is also available as a bill block. In the bill block, programs are listed as they appear on the bill, so the meter block and the bill block may differ if the meter's program enrollment changes over time.

// Enrolled Programs Block example
[
    {
        "name": "Net Energy Metering (NEM2)"
    }
]

This is an object type that represents a program that a service may be enrolled in.

Attribute Type Description
name String The name of the program.
 Extensible: We may extend this object type in the future, so be able to handle unknown attributes gracefully.