API Documentation

The EnergyID Web API lets you connect your own applications and systems to EnergyID and go beyond the integrations we provide out of the box. This page is the starting point for every API integration.

All endpoints are described in our API reference documentation. If your app only needs to send meter readings to a record, use Incoming Webhooks.

Authentication

EnergyID supports three ways to authenticate with the Web API. Which one you choose depends on the type of integration:

OAuth 2.0 for client apps that act on behalf of users who sign in and give consent themselves. Read Create a client app.
Personal API keys for your own scripts and small automations.
Workspace API keys for backend integrations owned by an organization. Read API keys for Workspaces.

How to choose the right method, which access each method grants, and how to send a key with a request is explained in Authentication methods.

Permission scopes

Scopes define which objects a token or key can access and which actions are allowed on them. A scope consists of the object followed by the action, for example records:write. A write scope also grants read access.

An OAuth app requests the scopes it needs. The user sees those scopes when they give your app consent. API keys get their scopes automatically, based on the type of key and the chosen access level.

Scope	Short description
profile:read	Read-only access to the user's profile.
profile:write	Read and write access to the user's profile.
records:read	Read-only access to the user's records.
records:write	Read and write access to the user's records.
workspaces:read	Read-only access to the Workspaces the user can access.
workspaces:write	Read and write access to the Workspaces the user can access.
groups:read	Read-only access to the user's groups.
groups:write	Read and write access to the user's groups.

If your app needs to keep access while the user is not active, also request offline_access. Read more in Create a client app.

Object models

All Web API endpoints return data in JSON format.

Some endpoints return simplified versions of the resource objects. In general, endpoints that return multiple objects return a list of simplified objects. Simplified objects always contain an id which can be used to get full details of the object.

Object	Short description
Workspace	The central working environment of an organization. A Workspace brings together records, users, roles, configuration and integrations.
Record	In general, a record represents a building with its own address. Records have a collection of meters.
Meter	Meter objects are a representation of actual, physical flows that can be measured. The meter's metric describes what flow is measured and where in the flow it is measured. To get a better overview, the meters are divided into themes.
Reading	A reading is one data point in the meter's flow. It consists of a timestamp, value and validation code.
Group	A group is a collection of records. Groups are being replaced by Workspaces: use Workspaces for new integrations.

Datasets

For each record we calculate performance metrics for energy, water, waste and mobility.

You can break down and filter results by one of the supported dimensions. Use one dimension for filtering and another for grouping.

Name

Description

Energy

energyEmissions

Energy Emissions (kg)

Measures energy CO2 emissions.
Measurement: Weighted Delivered Energy - Weighted Exported Energy
Weighting: CO2 emission factors (from kWh to kg CO2-equivalent)

Dimensions:

Name	Type	Filter	Grouping	Supported values
carrier	string	Yes	Yes	biomass, butane, districtCooling, districtHeating, electricity, fuelOil, liquidGas, naturalGas, solarThermal
type	string	Yes	Yes	electric, nonElectric

energyProduction

Energy Production (kWh)

Measures on-site energy production in kWh.
Measurement: Total Energy Production

Dimensions:

Name	Type	Filter	Grouping	Supported values
carrier	string	Yes	Yes	cogenElectricity, solarPhotovoltaic, solarThermal, wind
type	string	Yes	Yes	electric, nonElectric
meter	guid	No	Yes	The id of each energy production meter.

Water

waterUse

Water Use (l)

Measures water consumption in liter.
Measurement: Total Water Use

Dimensions:

Name	Type	Filter	Grouping	Supported values
type	string	Yes	Yes	drinkingWater, groundwater, rainwater
meter	guid	No	Yes	The id of each water consumption meter.

Waste

solidWaste

Solid Waste (kg)

Determines solid waste consumption in kg.
Measurement: Total Solid Waste

Dimensions:

Name	Type	Filter	Grouping	Supported values
fraction	string	Yes	Yes	electronicWaste, glass, organicWaste, paperAndCardboard, pmd, residualWaste, softPlastics
type	string	Yes	Yes	biodegradable, recyclable, residual, special
meter	guid	No	Yes	The id of each solid waste meter.

Mobility

distanceTravelled

Distance Travelled (km)

Determines the distance travelled in km.
Measurement: Total Distance Travelled

Dimensions:

Name	Type	Filter	Grouping	Supported values
vehicleType	string	Yes	Yes	bike, car, motor, scooter
meter	guid	No	Yes	The id of each mobility meter.

Benchmark

The following benchmark metrics are available for households and schools.

Benchmarks are only available if a minimum number of users are contributing their results to the calculation. Additionally, benchmarks are only calculated for calendar years and months.

Name	Description
energyEmissionsPerGsm	Energy Emissions per m² (kg) Benchmark the daily energy CO2 emissions per gross square meter. Measurement: Average Daily Energy CO2 Emissions / Total Gross Area Value-based filters: Energy Type
energyEmissionsPerOccupant	Energy Emissions per Occupant (kg) Benchmark the daily energy CO2 emissions per occupant. Measurement: Average Daily Energy CO2 Emissions / Total People Value-based filters: Energy Type
energyUsePerGsm	Energy Use per m² (kWh) Benchmark the daily energy consumption per gross square meter. Measurement: Average Daily Energy Use / Total Gross Area Value-based filters: Energy Type
energyUsePerOccupant	Energy Use per Occupant (kWh) Benchmark the daily energy consumption per occupant. Measurement: Average Daily Energy Use / Total People Value-based filters: Energy Type
waterUsePerOccupant	Water Use per Occupant (l) Benchmark the daily water consumption per occupant. Measurement: Average Daily Water Use / Total People Value-based filters: Water Type For the moment only drinkingWater is supported.

Timezones

Some requests allow for specifying timestamps or generate timestamps with time zone information. These requests explicitly provide an ISO 8601 timestamp with timezone information and look something like 2018-08-05T15:05:06+01:00.