Interval Blocks

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

To organize utility data for a Interval, we split data up into smaller objects called "blocks" and only include the blocks which are relevant to that Interval. 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 Interval Block Basic metadata about the Interval.
sources List(Source) A list of raw sources that were parsed to build the interval results.
readings List(Readings) The list of interval readings. If you build support for only one block, make it this one.
... We may add other blocks in the future, so be able to handle unknown types gracefully.
  • We currently have no utility-specific interval blocks, but someday we will and will add links to them here.

The Base Interval Block contains some basic service information related to the interval. We have this available so you can easily see tariff or service information alongside interval readings.

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_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"]
qualities List(IntervalQualities) Any quality properties that apply to all of the interval readings. If this is an empty list, then we weren't able to determine the quality of the interval readings. ["revenue"]
... We may add other attributes in the future, so be able to handle unknowns gracefully.
// Base Interval Block example
{
    "service_identifier": "1234222222-9",
    "service_tariff": "A6X",
    "service_address": "222 Broadway St, Suite 100",
    "meter_numbers": ["111.00222.333.002"],
    "qualities": []
}

Green Button xml often contains the quality of interval readings, which can be useful for analysis. We include any quality properties we find in a list on the base block. Below are the descriptions in quality available from the Green Button specification. If we use another source besides Green Button that has quality properties on it, we will map those qualities to the Green Button qualities below.

Type Description
revenue Intervals are valid and acceptable for billing purposes.
valid Intervals have gone through all required validation checks and either passed them all or has been verified.
manual Intervals were replaced or approved by a human.
estimated Intervals were estimated using other values.
questionable Intervals failed one or more checks.
derived Intervals were calculated.
projected Intervals have been calculated as a projection or forecast of future readings.
mixed Intervals have mixed quality characteristics.
raw Intervals have not gone through the validation.
normalized Intervals have been adjusted to account for weather.
other Intervals have some other characteristic.
validated Intervals have been validated and possibly edited and/or estimated in accordance with approved procedures.
verified Intervals failed at least one of the required validation checks but was determined to represent actual usage.
... We may add other types in the future, so be able to handle unknowns gracefully.

We bundle individual interval readings into chunks that have the same properties (source, reading quality, etc.) inside a single block, so that we aren't copying huge amounts of properties for each individual interval reading. In general we try to limit these interval reading chunks to weekly or monthly timespans, but they can vary in size due to differences in sources. For example, if we collect intervals daily, the interval chunks will generally be in days since the source changes for each day.

Attribute Format Description Example Utility Gotchas
start ISO8601 The interval reading start, in the local utility's timezone. "2016-01-01T12:30:00.000000-08:00"
end ISO8601 The interval reading end, in the local utility's timezone. "2016-01-01T12:30:00.000000-08:00"
kwh Float The net kilowatt hour (kWh) usage for the interval. 126.50
... We may add other attributes in the future, so be able to handle unknowns gracefully.
// Interval Reading Block example
{
    "start": "2015-01-07T08:30:00.000000-07:00",
    "end": "2015-02-05T08:45:00.000000-07:00",
    "kwh": 18.2
}