Builder APIConcepts
Energy data and data quality
EOS consumption of energy, water and waste - meters, carriers, units, confidence and cost coverage.
Energy, water and waste numbers come from EOS, Relynk's processed hourly consumption, never from raw meter readings.
The functions
meters.list: EOS meters with carrier, unit, and whether each counts in the building total (building meters) or is a sub-meter, virtual or tenant meter.meters.topology: the sub-meter tree, what virtual meters are calculated from, andoverlappingBuildingMeters.consumption.buildings: building totals per carrier, exactly as the Relynk portal's EOS dashboard shows them.consumption.meters: individual meters.
Carriers and units
A carrier is what is consumed: electricity, gas, thermal, thermal_heat,
thermal_cool, water and waste. Energy is in kWh, water in L and waste in kg.
Rules that keep the numbers right
- Take building consumption and cost from
consumption.buildings. Never compute it from raw meter points, never add sub-meters to a building meter (a sub-meter is already part of its parent), and never add different carriers together. - Values are whole hours: ranges must start and end on an hour, and day, week and month buckets of
consumption.buildingson Oslo midnight. Otherwise the call fails withinvalid_range. - For waste meters, a bucket without a pickup is 0. Everywhere else,
nullmeans no data.
Data quality
Every number comes with how much to trust it:
| Field | Meaning |
|---|---|
confidence | HIGH, MEDIUM, LOW or MISSING. Show it next to the number. |
estimatedShare | How much of the number is estimated rather than measured. |
costCoverage | How much of the consumption has a price. Below 1, the cost is incomplete. |
overlappingBuildingMeters | When not empty, the total counts that consumption twice, as the portal does. Say so. |
See the guide A building's energy use.