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.
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.
programs Enrolled Programs Information about programs the service is enrolled in.
  • Coming soon!

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

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"
Warning: We may add other attributes in the future, so be able to handle unknowns gracefully.
// Base Meter Block example
{
    "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.
Warning: We may add other service classes in the future, so be able to handle unknowns gracefully.

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.

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.
Warning: We may add other attributes in the future, so integrations should be able to handle attributes beyond those currently listed.
{
    "name": "Net Energy Metering (NEM2)"
}