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.
 Extensible: We may add blocks in the future, so be able to handle unknown attributes 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"]
 Extensible: We may extend this object type in the future, so be able to handle unknown attributes 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.
 Extensible: We may add variants to this enumeration type in the future, so be able to handle unknown values 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 or null The net kilowatt hour (kWh) usage for the interval. 126.5
datapoints List(Datapoint) A list of all the values for this time period, for example forward, reverse, and net usage if a meter has one channel for each flow direction. [{"type": "fwd", "unit": "kwh", "value": 107.3}, ...]
 Extensible: We may extend this object type in the future, so be able to handle unknown attributes gracefully.

A datapoint represents a specific value read from the meter at the time of the interval that contains it. For example, if a meter provides both usage and demand data then there will be two datapoints for each moment in time: one usage value and one demand value.

Attribute Format Description Example
meter_number String (Optional) The ID number of the measurement device that recorded this value. This field is optional and so may be missing from datapoints for meters that don't have it. "G11010101"
type Datapoint Type The type of value represented by this datapoint. "fwd"
unit Unit The unit of measure for this datapoint's value. "therms"
value Float The value of this datapoint. 503.841
 Extensible: We may extend this object type in the future, so be able to handle unknown attributes gracefully.

There are many different types of meter readings we see so we use Datapoint Types to indicate what a certain meter reading value means.

Type Description Multiplicity
fwd Forward usage, i.e. energy consumed from the grid. A reading may contain multiple datapoints of this type, at most one per meter number.
net Net usage, usually just forward usage minus reverse usage. This matches the deprecated kwh value on the reading object. If the reading contains data from multiple meters, this value represents the aggregate net usage for all of them. A reading may contain at most one datapoint of this type. In rare cases there may be no datapoint of this type if we weren't able to determine the overall net usage.
rev Reverse usage, i.e. energy sent back into the grid. A reading may contain multiple datapoints of this type, at most one per meter number.
gen Generated energy, for example from an on-site solar array or fuel cell generator. NOTE: gen intervals may not be reflected in the billed usage like other types of intervals are. A reading may contain multiple datapoints of this type, at most one per meter number.
max Maximum value seen during an interval period; usually used for max demand. A reading may contain multiple datapoints of this type, at most one per meter number.
 Extensible: We may add variants to this enumeration type in the future, so be able to handle unknown values gracefully.

Examples

// Interval Reading Block example
{
    "start": "2015-01-19T08:30:00.000000-08:00",
    "end": "2015-01-19T08:45:00.000000-08:00",
    "kwh": 18.2,
    "datapoints": [
        {
            "type": "net",
            "unit": "kwh",
            "value": 18.2
        }
    ]
}
{
    "start": "2021-07-09T13:20:00.000000-07:00",
    "end": "2021-07-09T13:25:00.000000-07:00",
    "kwh": 3.1,
    "datapoints": [
        {
            "type": "fwd",
            "unit": "kwh",
            "value": 24.8
        },
        {
            "type": "net",
            "unit": "kwh",
            "value": 3.1
        },
        {
            "type": "rev",
            "unit": "kwh",
            "value": 21.7
        }
    ]
}
{
    "start": "2019-04-24T11:00:00.000000-06:00",
    "end": "2019-04-24T11:15:00.000000-06:00",
    "kwh": 4.1,
    "datapoints": [
        {
            "type": "net",
            "unit": "kwh",
            "value": 4.1
        },
        {
            "type": "max",
            "unit": "kw",
            "value": 18.4
        }
    ]
}
{
    "start": "2020-08-12T18:00:00.000000-04:00",
    "end": "2020-08-12T19:00:00.000000-04:00",
    "kwh": null,
    "datapoints": [
        {
            "type": "net",
            "unit": "therms",
            "value": 9.5
        }
    ]
}
{
    "start": "2015-04-24T16:20:00.000000-05:00",
    "end": "2015-04-24T16:25:00.000000-05:00",
    "kwh": 12.01,
    "datapoints": [
        {
            "meter_number": "1000005",
            "type": "fwd",
            "unit": "kwh",
            "value": 3.46
        },
        {
            "meter_number": "1000006",
            "type": "fwd",
            "unit": "kwh",
            "value": 8.54
        },
        {
            "type": "net",
            "unit": "kwh",
            "value": 12.01
        }
    ]
}