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.
null
, it either hasn't
been found yet or doesn't exist. But if the meter's
status
is updated
and there's a
meters_full
meter note,
we finished collection successfully, so any data still missing is unavailable.
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. |
Example:
// 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. |
Example:
// 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.
Example:
// 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.
Example:
// 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. |