Meter Blocks

You will see the Meter blocks included in a Meter object listed under Meter['blocks'].

To organize utility data for a Meter, we split data up into smaller objects called "blocks" and only include the blocks which are relevant to that Meter. We use blocks to make developing integrations with our API faster and easier. You only have to use the blocks you want to support and can ignore the rest. Then, if you ever want to do more complex utility data analysis, you can add support for additional blocks at your own pace. Our goal is to minimize the time it takes to get your initial prototype up and running, then allow you expand features and capabilities using more blocks and as you need to.


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 Format Description
base Base Meter Block Basic information about the Meter. If you build support for only one block, make it this one.
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.
... We may add other blocks in the future, so be able to handle unknown types gracefully.
  • 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 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"
... 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 is a basic categorization for a particular tariff. This categorization is extremely simplistic and not necessarily the same categorization as each utility. If you want more detailed service class analysis, please use the service_tariff.

Type 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 A tariff we haven't categorized yet or are unable to tell what catetgory it is in.
... 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.

Attribute Format Description Example Utility Gotchas
suppliers List(Supplier Info) A list of supplier info objects describing any third party suppliers for this meter.
// 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"