Columns
Column | Required | Description |
activity_ref_id | Yes | The ref_id of the activity this usage belongs to |
ref_id | Yes | Identifier for this consumption, unique within its activity |
starts_at | Yes | Period start (YYYY-MM-DD) |
ends_at | Yes | Period end (YYYY-MM-DD) |
actual | Yes |
|
data.magnitude | Yes | The quantity |
data.unit | Yes | The unit, for example |
data.resource | Yes | What is measured, for example |
note | Column required, value optional | Free-text note |
Key: activity_ref_id + ref_id
The three data. columns (data.magnitude, data.unit and data.resource) can be repeated to record more than one consumption value on the same row, for example fuel used and distance driven for a vehicle. See “Recording more than one measurement per row” below for an example.
Example
activity_ref_id | ref_id | starts_at | ends_at | actual | data.magnitude | data.unit | data.resource | note |
denver-office-electricity | denver-office-electricity-2025-01-01-2025-01-31 | 2025-01-01 | 2025-01-31 | 1 | 12400 | kWh | electricity_purchased |
|
denver-office-natural-gas | denver-office-natural-gas-2025-01-01-2025-01-31 | 2025-01-01 | 2025-01-31 | 1 | 310 | therm | heat_content |
|
Naming the ref_id
We recommend <activity_ref_id>-<starts_at>-<ends_at>, as in the example above. The ref_id only has to be unique within its activity.
Recording more than one measurement per row
To record two measurements for the same period, such as fuel used and miles driven for a vehicle, repeat the three data. columns. Every repeat needs all three columns, in the order magnitude, unit, resource.
activity_ref_id | ref_id | starts_at | ends_at | actual | data.magnitude | data.unit | data.resource | data.magnitude | data.unit | data.resource | note |
truck-07 | truck-07-2025-01-01-2025-01-31 | 2025-01-01 | 2025-01-31 | 1 | 410 | gallon | volume_fuel_combusted | 3900 | mile | distance_traveled |
|
Each row must have at least one complete set filled in.
Units
The unit must match the resource's unit type. For example, electricity_purchased needs an energy unit such as kWh or MWh. See Consumptions, resources and units for the full list.
Common problems
Overlapping periods for the same activity double count usage, unless each record holds a truly distinct value.
Start and end dates reversed. Check that each start date comes before its end date.
Reusing a ref_id twice for one activity in the same file stops the upload.