1. Documentation
2. API
3. Intervals
4. Blocks

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.

---

Interval Block Type

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.

Universal Interval Blocks

Utility Specific Interval Blocks

We currently have no utility-specific interval blocks, but someday we will and will add links to them here.

---

Base Interval Block

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.

Example:

// 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": []
}

Interval 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.

---

Interval Readings Block

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.

Datapoint

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.

Datapoint Type

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

Examples

Intervals with only one channel of usage data (this is the most common case):

// 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
        }
    ]
}

Example intervals with separate forward and reverse usage:

{
    "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
        }
    ]
}

Example interval data for a meter with both demand and usage

{
    "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
        }
    ]
}

Interval data for a gas meter

{
    "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
        }
    ]
}

Example readings block for multiple meters all with their own meter numbers

{
    "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
        }
    ]
}