Bill Blocks

You will see the Bill blocks included in a Bill object listed under 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. 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 Bill Block Basic information about the Bill. If you build support for only one block, make it this one.
sources List(Source) A list of raw sources that were parsed to build the bill results.
line_items List(Line Item) The list of charges that make up the bill.
suppliers List(Supplier Info) Information about the entity that supplied the energy listed on this bill.
tiers List(Tier Item) A breakdown of any tier charges for a bill.
tou List(Time-of-Use Item) A breakdown of any time-of-use charges for a bill.
demand List(Demand Item) A breakdown of any demand charges for a bill.
power List(Power Item) A listing of any reactive power or power factor information from a bill.
... We may add other blocks in the future, so be able to handle unknown types gracefully.
Type Format Description
pge_details PGE Bill Block PG&E-specific details. Currently, only serial (billing schedule) is supported
sce_details SCE Bill Block SCE-specific details. Currently, only voltage is supported
sdge_details SDGE Bill Block SDGE-specific details. Currently, only voltage is supported
pge_nem_details PG&E NEM Bill Block PG&E Net Energy Metering Details.
sce_nem_details SCE NEM Bill Block SCE Net Energy Metering Details.
pge_bill_details PG&E Electric Details Block Information from PG&E "Electric Detail of Bill" documents.

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

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" SCE HTML bills don't have tariff information so we return an empty string in this field.
service_class ServiceClassType The class of utility service. This is usually derived from the 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. There may be cases when the utility will not provide the billing contact "John Smith"
billing_address String Where the bills are sent. This is what the utility provides, and may not be a full address. There may be cases when the utility will not provide the billing address "123 MAIN ST"
billing_account String The utility billing account id. "2-000-1111-22"
bill_statement_date ISO8601 The date the utility generated this bill, in the local utility's timezone. "2016-01-01T00:00:00-07:00"
bill_start_date ISO8601 The overall start date for the billing period, in the local utility's timezone. "2016-01-01T00:00:00-07:00"
bill_end_date ISO8601 The overall end date for the billing period, in the local utility's timezone. "2016-01-01T00:00:00-07:00"
bill_total_cost Float The total bill charges for the service. 432.25
bill_total_volume Float or null The total volume for the bill. Will be either kWh or therms depending on the value of bill_total_unit. 1000.0
bill_total_unit Unit What bill_total_volume is measured in. kwh
bill_total_kwh Float or null The total kwh for the bill. 1000.0
... We may add other attributes in the future, so be able to handle unknowns gracefully.
// 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 are individual charges for a Bill.

Attribute Format Description Example Utility Gotchas
name String The name for the the line item. See each utility's docs for a list of known line items for that utility. "Nuclear decommissioning"
start ISO8601 The start date for the line item, in the utility's local timezone. "2016-01-01T00:00:00-07:00"
end ISO8601 The end date for the line item, in the utility's local timezone. "2016-01-01T00:00:00-07:00"
cost Float or null The amount charged for the line item. A negative value indicates that this line item is a credit. A null indicates that this line item doesn't have a charge (e.g. it's some other non-charged or informative line item). -10.02
volume Float or null The quantity of unit measured for this line item. A null indicates that this line item doesn't have a volume (e.g. it's a flat fee or other charge). 12000.0
rate Float or null The cost per unit volume for this line item. A null indicates that this line item doesn't have a rate (e.g. it's a flat fee or other charge). 0.00345
unit Unit or null The unit for which this line item charges. A null indicates that this line item doesn't have a unit (e.g. it's a flat fee or other charge). "kwh"
// Line Item Bill Block 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"
}
Type Description
kwh Kilowatt hours (e.g. usage)
kw Kilowatts (e.g. demand)
kvar Reactive Power
kvarh Reactive Energy
therms Natural gas energy (wikipedia)
hcf Water volume in hundreds of cubic feet
days Days
months Months
percent Percent
lamps Number of Lamps (used in certain Outdoor Lighting Tariffs)
currency Amount of currency (currently only USD is supported)
... We may add other units in the future, so be able to handle unknown units gracefully.

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.

Attribute Format Description Example Utility Gotchas
supplier_type SupplierType What kind of supplier the information in this block is about. "cca"
supplier_name String or null The name of the supplier. "MCE"
supplier_service_id String or null The supplier's identifier for the service this bill is for. "055123315Q"
supplier_tariff String or null The name of the tariff used by this supplier. "RES-1"
supplier_line_items List(LineItem) The line item charges issued by the supplier. [{"name": "Energy Charge", ...}, ...] The list may be empty for certain supplier types.
supplier_total_cost Float or null The total amount charged by the supplier. 1024.0
supplier_total_volume Float or null The total volume (of electricity, gas, etc.) provided by the supplier. 993.81
supplier_total_unit Unit or null The units for the supplier_total_volume. "kwh"
... We may add other attributes in the future, so be able to handle unknowns gracefully.

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

Example bill with a third party electricity supplier
// Suppliers Block example for third party supplier
{
    "supplier_line_items": [
        {
            "cost": 87.41,
            "end": "2015-01-01T04:00:00.000000+00:00",
            "start": "2015-02-01T04:00:00.000000+00:00",
            "name": "SUPPLY CHARGE",
            "rate": 0.0791,
            "unit": "kwh",
            "volume": 1105.0
        }
    ],
    "supplier_name": "ACME ELECTRIC SUPPLY, INC",
    "supplier_service_id": null,
    "supplier_tariff": null,
    "supplier_total_cost": 87.41,
    "supplier_total_unit": "kwh",
    "supplier_total_volume": 1105.0,
    "supplier_type": "third_party"
}

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

Example PG&E CCA bill
// Suppliers Block CCA example
{
    "supplier_line_items": [
        {
            "cost": 20.88,
            "end": "2020-08-30T07:00:00.000000+00:00",
            "start": "2020-09-29T07:00:00.000000+00:00",
            "name": "GENERATION-TOTAL",
            "rate": 0.06935,
            "unit": "kwh",
            "volume": 301.15
        },
        {
            "cost": 1.01,
            "end": "2020-08-30T07:00:00.000000+00:00",
            "start": "2020-09-29T07:00:00.000000+00:00",
            "name": "Local Utility Users Tax",
            "rate": null,
            "unit": null,
            "volume": null
        },
        {
            "cost": 0.07,
            "end": "2020-08-30T07:00:00.000000+00:00",
            "start": "2020-09-29T07:00:00.000000+00:00",
            "name": "Energy Surcharge",
            "rate": null,
            "unit": null,
            "volume": null
        }
    ],
    "supplier_name": "Sonoma Clean Power",
    "supplier_service_id": "0123456789",
    "supplier_tariff": "NEM E-1",
    "supplier_total_cost": 21.96,
    "supplier_total_unit": "kwh",
    "supplier_total_volume": 301.15,
    "supplier_type": "cca"
}

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.

Attribute Format Description Example Utility Gotchas
name String The name for the the tier. See each utility's docs for a list of known tier names for that utility. "Baseline"
level Integer A basic tier level indicator. Since utilities have different names for tiers, this integer lets you sort tiers easily without knowing all the names. 1
cost Float or null The amount charged for this tier. A null indicates that this tier doesn't have a charge (e.g. it may have a volume but no cost). 10.02
volume Float or null The quantity of unit measured for this tier. A null indicates that this tier doesn't have a volume (e.g. it may have a cost but no volume). 12000.0
unit Unit or null The unit for this tier. A null indicates that this tier doesn't have a unit (e.g. it may have a cost but no volume or unit). "kwh"
// Tier Bill Block example
{
    "name": "Tier 1 Usage",
    "level": 1,
    "cost": 52.88,
    "volume": 327.0,
    "unit": "kwh"
}

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.

Attribute Format Description Example Utility Gotchas
name String The name for the TOU charge. See each utility's docs for a list of known TOU names for that utility. "On-Peak"
bucket BucketType A basic TOU bucket type. Since utilities have different names for Time-of-Use periods (i.e. buckets), this is our basic universal name the type of TOU charge. "peak"
cost Float or null The amount charged for this TOU bucket. A null indicates that this bucket doesn't have a charge (e.g. it may have a volume but no cost). 10.02
volume Float or null The quantity of unit measured for this TOU bucket. A null indicates that this bucket doesn't have a volume (e.g. it may have a cost but no volume). 12000.0
unit Unit or null The unit for this TOU bucket. A null indicates that this bucket doesn't have a unit (e.g. it may have a cost but no volume or unit). "kwh"
// Time-of-Use Bill Block example
{
    "name": "On-Peak Usage",
    "bucket": "peak",
    "cost": 52.88,
    "volume": 327.0,
    "unit": "kwh"
}
Type Description
peak Peak time periods. Generally during the middle of the day.
off-peak Off peak time periods. Generally during the evening and night.
part-peak Part peak time periods. Generally during the morning and/or evenings.
super-peak Super peak time periods. Generally during the highest demand part of the day.
super-off-peak Super off peak time periods. Generally during the lowest demand part of the day.
other Some other time period. Please see the name for further information.

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.

Attribute Format Description Example Utility Gotchas
name String The name for the demand charge. See each utility's docs for a list of known demand charge names names for that utility. "Max demand"
cost Float or null The amount charged for this demand charge. A null indicates that this demand doesn't have a charge (e.g. it may have a demand amount but no cost). 10.02
demand Float or null The kW demand value. A null indicates that this bucket doesn't have an amount (e.g. it may have a fixed cost for some service demand size). 243.1
// Demand Bill Block example
{
    "name": "Peak Demand Charge",
    "cost": 52.88,
    "demand": 327.0
}

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.

Attribute Format Description Example Utility Gotchas
type PowerItemType The type of power item captured by this object. Since different utilities use different names for the same type of reading this is our universal identifier for the various reading types. "reactive_demand"
name String The name of the reading as it appears on the bill. "Billable Reactive-Power demand"
unit Unit or null The unit of the reading - note that some reading types (e.g power factor) are unitless and so will have this field set to null. "kvar"
volume Float The value of the reading. 1666.7
// 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
    }
]
Type Description
reactive_demand Reactive demand measured by the utility, usually in kVar
reactive_usage Reactive usage measured by the utility, usually in kVarh
real_demand Real demand measured by the utility, usually in kW
power_factor Power factor