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,
"previous_balance": 255.63,
"amount_paid": 255.63,
"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.
Daily Bill Data
GET /days
Returns an array of days on which bills were saved for the authenticated client.
GET /days/:date
Returns the bills for the specified date for the authenticated client. Supports an optional format query parameter to return the response in XML format.
Optional XML Flag
The format query parameter in the /days/:date?format=xml endpoint allows the response to be returned in XML format that is cross-compatible with Urjanet’s schema when set to format=xml. No other formats are currently supported (Feel free to send us a feature request!). If omitted or set to any other value, the response is returned in JSON format. When XML is requested, the Content-Type header is set to text/xml, and the response body contains the bills data formatted as XML.
You can see an example XML delivery here
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: