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

Bill Blocks

To organize utility data for a bill, we split data up into smaller objects called "blocks" and only include the blocks which are relevant to that bill. 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 bill, it appears under the attribute corresponding to its type name documented here. The type names of all blocks available for a given bill are also listed in the blocks attribute on the bill object.

---

Bill 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 Bill Blocks

Utility Specific Bill Blocks

---

Base Bill Block

The Base Bill Block contains some basic information about the utility bill.

Example:

// Base Bill 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",
    "bill_start_date": "2015-01-07T00:00:00.000000-08:00",
    "bill_end_date": "2015-02-05T00:00:00.000000-08:00",
    "bill_total_cost": 194.78,
    "bill_total_volume": 837.0,
    "bill_total_unit": "kwh",
    "bill_total_kwh": 837.0
}

---

Line Items Bill Block

Line items are individual charges for a Bill.

Example:

{
    "name": "Tier 1 Usage",
    "start": "2015-01-07T08:00:00.000000+00:00",
    "end": "2015-02-05T08:00:00.000000+00:00",
    "cost": 52.88,
    "volume": 327.0,
    "rate": 0.1617,
    "unit": "kwh",
    "kind": "supply"
}

---

ChargeKind

This String type enumerates the possible categories utilities often use to classify line item charges.

Suppliers Block

The Suppliers block contains information about the energy suppliers on a particular bill. For example, this block might contain information about CCAs or third party electricity/gas suppliers.

Example third party supplier

This example shows the third party supply section of a residential electric bill and its corresponding suppliers block.

Example CCA bill

This example shows a CCA section from a PG&E bill and its resulting suppliers block.

---

Tier Items Bill Block

Tiers is a common way to charge customers for different amounts of usage. Since many utilities have tiers, we have created a universal block to break these down so you only have to build support for the Tiers Bill Block to perform basic tier analysis across many utilities.

Example:

// Tier Bill Block example
{
    "name": "Tier 1 Usage",
    "level": 1,
    "cost": 52.88,
    "volume": 327.0,
    "unit": "kwh"
}

---

Time-of-Use Bill Block

Time-of-Use (TOU) is a common way to charge customers different rates at different times of the day (e.g. "buckets"). Since many utilities have TOU, we have created a universal block to break these down so you only have to build support for the Time-of-Use Bill Block to perform basic TOU analysis across utilities that have TOU charges.

Example:

// Time-of-Use Bill Block example
{
    "name": "On-Peak Usage",
    "bucket": "peak",
    "cost": 52.88,
    "volume": 327.0,
    "unit": "kwh"
}

Time-of-Use Bucket Type

---

Demand Bill Block

Demand charges are a common way to charge customers for their power demand kW (as opposed to usage kWh). Since many utilities have demand charges, we have created a universal block to break these down so you only have to build support for the Demand Bill Block to perform basic demand charge analysis across many utilities.

Example:

// Demand Bill Block example
{
    "name": "Peak Demand Charge",
    "cost": 52.88,
    "demand": 327.0
}

---

Power Bill Block

Many utilities charge their customers (especially large commercial customers) for reactive demand (usually in kVar) in addition to real demand (usually in kW). Because this information is often presented differently by different utilities, we've created a power block that breaks down this data so that users who want to perform power factor analysis across many utilities only have to build support for one block.

Example:

// Power Bill Block example
[
    {
        "name": "Reactive Demand",
        "type": "reactive_demand",
        "unit": "kvar",
        "volume": 291.3
    },
    {
        "name": "Real Demand",
        "type": "real_demand",
        "unit": "kw",
        "volume": 1501.4
    },
    {
        "name": "Power Factor",
        "type": "power_factor",
        "unit": null,
        "volume": 0.98
    }
]

Power Item Type