Raw Bill Data
Familiarize yourself with our relational heirarchy of utility billing data.
Utility Account
A UtilityAccount represents a customer account with a Utility Company. They have many UtilityBills.
{
"id": 4887,
"ep_object_type": "UtilityAccount",
"utility_company_name": "Constellation Energy",
"status": "Active",
"acct_num": "1-4887",
"latest_invoice_date": "2020-05-05T00:00:00.000Z",
"delivery_method": "Automated",
"delivery_name": "Trinity",
"delivery_email": "tr1nity@riseup.net",
"master_acct_num": "1842-8814",
"online_access_url": "https://constellation.com",
"metadata": {
"native_account_id": 4887,
"account_active": true
},
"created_at": "2015-07-30T18:29:31.000Z",
"updated_at": "2022-02-10T05:53:42.000Z"
}
Utility Account Endpoints
All data endpoints require Authentication.
List Accounts
GET /utility_accounts
Returns a list of the UtilityAccounts accessible to you in EnergyPrint.
Get one Account
GET /utility_accounts/:id
Returns the UtilityAccount with the corresponding id, with its UtilityMeters nested inside.
Get Account’s Bills
GET /utility_accounts/:id/bills
Returns the UtilityAccount with the corresponding id, with its UtilityBills nested inside.
Edit Utility Account Metadata
PUT /utility_accounts/:id
Updates a UtilityAccounts metadata object with the request body. Returns the updated UtilityAccount.
Utility Bill
A UtilityBill contains multiple UtilityCharges and UtilityUsages. A bill belongs to a single UtilityAccount, and may apply to multiple UtilityMeters.
{
"id": 252784,
"ep_object_type": "UtilityBill",
"utility_account_id": 4887,
"original_utility_bill_id": null,
"invoice_date": "2020-12-28T00:00:00.000Z",
"estimated": false,
"account_holder_name": "Morpheus",
"amount_due": 358.22,
"amount_paid": 255.63,
"previous_balance": 0,
"archived": false,
"archive_reason": null,
"metadata": {},
"source": {
"format": "pdf",
"expiring_link": "https://energyprint-production.s3.us-east-2...",
"expiresIn": "7d"
},
"charges": [ <UtilityCharge>, <UtilityCharge> ],
"usages": [ <UtilityUsage> ],
"created_at": "2022-02-10T18:29:31.000Z",
"updated_at": "2022-02-10T05:53:42.000Z"
}
Utility Charge
A UtilityCharge represents a charge line item on a bill. It is owned by a UtilityBill and a UtilityMeter.
{
"id": 7596676,
"ep_object_type": "UtilityCharge",
"utility_bill_id": 1392209,
"utility_account_id": 4887,
"utility_meter_id": 2509,
"amount": 1147.7,
"description": "First 4000 kWh",
"utility_charge_type": "usage_cost",
"start_date": "2014-04-03T00:00:00.000Z",
"end_date": "2014-05-01T00:00:00.000Z",
"line_item_group_id": "5c29e7ba-db0b-4626-9c5a-861620ec4173"
}
Utility Usage
A UtilityUsage is owned by a single UtilityBill and a UtilityMeter and represents a charge line item on a bill.
{
"id": 2698837,
"ep_object_type": "UtilityUsage",
"utility_bill_id": 1392209,
"utility_account_id": 4887,
"utility_meter_id": 2509,
"amount": 23520,
"estimated_meter_read": false,
"description": "Total kWh",
"utility_usage_type": "usage_amount",
"measurement_unit": "kWh",
"start_date": "2014-04-03T00:00:00.000Z",
"end_date": "2014-05-01T00:00:00.000Z",
"kbtus": 80250.24,
"lbs_co2": 42336,
"gallons": 0,
"supply": false,
"line_item_group_id": "21761aec-407b-11e5-85cf-bc764e04355d"
}
Bill Endpoints
The following endpoints return raw bill data in the form of UtilityBills, UtilityCharges, and UtilityUsages:
A UtilityBill is owned by a single UtilityAccount and applies to one or more UtilityMeters. Edited bills will include an original_utility_bill_id that refers to the original, archived bill. This allows you to easily react to and record edits to your billing data.
Calendar-Normalized Data
Snapshot Info
SnapshotInfo is a year-normalized look at how a property’s EUI, ECI, carbon output, and ENERGY STAR score are trending, year-over-year, in three key metrics.
A complete SnapshotInfo requires two years of complete bill data to generate.
{
"property_id": 1426,
"ep_object_type": "SnapshotInfo",
"effective_month": "2019-02-01T00:00:00.000Z",
"ENERGY_STAR_rating": 61,
"current_cost_per_sq_ft": 1.4069,
"previous_cost_per_sq_ft": 1.2589,
"yoy_percent_change_cost_per_sq_ft": -0.1052,
"current_kbtus_per_sq_ft": 73.4344,
"previous_kbtus_per_sq_ft": 69.9487,
"yoy_percent_change_kbtus_per_sq_ft": -0.0475,
"current_co2_per_sq_ft": 22.7956,
"previous_co2_per_sq_ft": 22.3907,
"yoy_percent_change_co2_per_sq_ft": -0.0178,
"created_at": "2022-02-10T05:40:34.000Z",
"updated_at": "2022-02-10T05:40:34.000Z"
}
current metrics are derived from data over the 12 months preceding the snapshot’s effective_month.
previous metrics are derived form data over the 12 months preceding the current period.
A property will have SnapshotInfo available once it has 12 months of complete bill history.
Endpoint
Snapshots are generated per-property. You can get them using this endpoint:
Monthly Consumption Data
Monthly Consumption Data is your utility bill data, date-adjusted to be normalized by month.
Monthly Consumption Data are available for an entire Property, a single UtilityMeter or an Energy Type. (e.g. ELECTRIC).
{
"id": 1480956,
"ep_object_type": "MonthlyConsumptionData",
"utility_meter_id": 2509,
"effective_month": "2020-08-01T00:00:00.000Z",
"distribution_kbtus": 120083.1387,
"distribution_lbs_co2": 63349.8387,
"supply_kbtus": 120083.1387,
"supply_lbs_co2": 63349.8387,
"demand_consumption": 0,
"usage_cost": 1650.02,
"demand_cost": 45.04,
"service_cost": 0,
"interim_rate_cost": 0,
"other_applied_cost": 0,
"tax_cost": 20.02,
"total_cost": 1715.08,
"gallons": 0,
"estimated": false,
"month_complete": true,
"created_at": "2021-05-01T14:09:55.000Z",
"updated_at": "2021-05-01T14:09:55.000Z"
}
Endpoints
The following endpoints return Monthly Consumption Data: