API Documentation

Web API

EnergyID Web API allows Apps to integrate with EnergyID and go beyond the integrations we provide out of the box.

You can get a detailed description of all the available endpoints in our API reference documentation. If your App only needs to post meter readings to an EnergyID record, use our Incoming Webhooks.

Authentication

EnergyID Web API uses the OAuth 2.0 protocol for authentication and authorization. EnergyID supports common OAuth 2.0 scenarios such as those for web server, installed, and client-side applications.

All applications follow a basic pattern when accessing the EnergyID Web API using OAuth 2.0. At a high level, you follow four steps:

  1. Obtain OAuth 2.0 credentials.

    Register your app to obtain OAuth 2.0 credentials such as a client ID and client secret.

  2. Obtain an access token from the EnergyID Authorization Server.

    Before your application can access private data using the EnergyID Web API, it must obtain an access token. A variable parameter called scope controls the set of resources and operations that an access token permits. During the access-token request, your application sends one or more values in the scope parameter.

    To begin, request an authorization code for your app. Call GET https://identity.energyid.eu/connect/authorize and fill the following parameters:

    • client_id - issued when you created your app
    • scope - permissions to request (see below)
    • response_type - should be set to code
    • redirect_uri - the callback URL that will catch the authorization code
    • state - unique string to be passed back upon completion (optional)
    • ui_locales - gives a hint about the desired display language of the login and user consent screen, for example en-GB, nl-BE (optional)

    Our interactive OAuth flow requires an authentication step where the user logs in with their EnergyID account. After logging in, the user is asked whether they are willing to grant the permissions that your application is requesting. This process is called user consent. If the user grants the permission, the EnergyID Authorization Server sends your application an authorization code that your application can use to obtain an access token. If the user does not grant the permission, the server returns an error.

    The authorization code is passed to your redirect URL along with the requested scopes. You can now exchange this authorization code for an access token by calling POST https://identity.energyid.eu/connect/token.

    • client_id - issued when you created your app
    • client_secret - issued when you created your app
    • grant_type - should be set to authorization_code
    • code - the authorization code obtained by the previous call
    • redirect_uri - the URL to be redirected to after authorization (this must be the same uri as the one from the previous call)

  3. Send the access token to an API endpoint.

    Whenever making any API request to EnergyID, you will need to include your access token in the request headers. Authorization: bearer {AccessToken}.

  4. Refresh the access token, if necessary.

    Access tokens have limited lifetimes. If your application needs access to the EnergyID Web API beyond the lifetime of a single access token, it can obtain a refresh token. A refresh token allows your application to obtain new access tokens. Call POST https://identity.energyid.eu/connect/token and pass the following body:

    • client_id - issued when you created your app
    • client_secret - issued when you created your app
    • grant_type - should be set to refresh_token
    • refresh_token - the refresh token obtained along with the access token

    Note that a refresh token is only provided when you include the offline_access scope in the authorize call.

Permission scopes

OAuth scopes let you specify exactly how your app needs to access a member's account. As an app developer, you specify your desired scopes in the initial OAuth authorization request. When a member is responding to your OAuth request, the requested scopes will be displayed to them when they are asked to approve your request.

EnergyID uses scopes that refer to the object they grant access to, followed by the class of actions on that object they allow (e.g. records:write).

The list of objects includes records, groups and profile. The supported actions are read and write.

Scope Short description
profile:read Read only access to the member's profile
profile:write Full access to the member's profile
records:read Read only access to the member's records
records:write Full access to the member's records
groups:read Read only access to the member's groups
groups:write Full access to the member's groups

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 will 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
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.

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.

Register your application

If you want to use the EnergyID Web API or distribute your Incoming Webhook as an App, you should first register your application. You can do this by sending us an email with the following information:

  • Application name
  • An icon for the application
  • URL to the application’s home page
  • A short description of the application
  • A link to the application’s privacy policy
  • A list of redirect URLs
  • A list of required scopes