The Disaggregation Engine API.

Overview

The Disaggregation engine contains a python package and an api that can find the likely consumption distribution for energy and natural gas in a building, starting from more generic data, a process known as disaggregation. The API accepts specific inputs as payload. Please refer to the swagger documentation and testing page here.

Usage

To get started with the Disaggregation Engine API please follow the step by step instructions for testing the API below:

• Link for swagger documentation: /swagger
• Please make sure the site is secure and there is a lock symbol in the address bar if not prefix https:// before the link
• Click on the authorise button
• Use your client ID to authenticate and then to authorise
• When asked use the single sign on page
• Select the appropriate API endpoint depending on whether you want the results disaggregated on a monthly (i.e. /api/v1/disaggr/monthly), or an annual (/api/v1/disaggr/annual), basis
• Click on the Try it out button for the selected API endpoint
• Please read carefully the Compatible Input Combinations section
• Select the csv file to upload.
• Select the building typology from the dropdown menu
• Select the energy vectors from the dropdown menu
• Select the input type from the dropdown menu
• Please press execute in order to run the API

The service requires the user to input data in the following format:

Building Typology

The building_typology input is used to determine the best model to match the disaggregation. Different building types use energy differently. It can be one of the following values:

• Residential
• Office
• School
• Retail

Energy Vectors

The energy_vectors input is used to determine the shape of the data uploaded, as well as the best model to match the disaggregation. A building that uses both electricity and natural gas will have different distributions of usage than one that only uses electricity. It can be one of the following values:

• Electricity
• Natural gas and electricity

Input type

The input_type input is used to determine the format of the data uploaded. It can be one of the following values:

• Cumulative: a series of readings showing the cumulative consumption for every time step (e.g. from energy meters)
• Monthly consumption: a series of readings showing the monthly consumption (e.g. from energy bills)

Csv File

The csv_file input is used to choose the csv file that includes the dataset to be uploaded. Please make sure to provide a dataset with energy consumption values for each energy vector selected, either cumulative readings from energy meters or monthly totals from energy bills. Therefore, the csv file dataset should contain the following columns:

• date: The date of the reading. Mandatory
• time: The time of the reading. Mandatory only if the input_type=Cumulative
• Electricity Energy Meter Reading: the value of electricity meter reading. Mandatory.
• Natural Gas Energy Meter Reading: the value of natural gas meter. Mandatory only if energy_vectors=Natural gas and electricity.

Examples:

Csv File for input_type=Cumulative and energy_vectors=Electricity

date,time,Electricity Energy Meter Reading
31/12/2024,22:10,551
31/12/2024,22:20,551
31/12/2024,22:30,551
31/12/2024,22:40,551
31/12/2024,22:50,551
[...]
      

Csv File for input_type=Monthly consumption and energy_vectors=Electricity

date,Electricity Energy Meter Reading
31/01/2024,551
28/02/2024,651
31/03/2024,751
30/04/2024,851
31/05/2024,951        
      

Csv File for input_type=Monthly consumption and energy_vectors=Natural gas and electricity

date,Electricity Energy Meter Reading,Natural Gas Energy Meter Reading
31/01/2024,2551,5551
28/02/2024,2651,4651
31/03/2024,2751,3751
30/04/2024,2851,2851
31/05/2024,2951,1951
      

Compatible Input Combinations

Please make sure to select the combination of energy_vectors and input_type inputs that corresponds to the shape and format of the csv file dataset uploaded, irrespective of whether you want the results disaggregated on a monthly, or annual, basis. Please note that other combinations of energy_vectors and input_type inputs may result in irrelevant, empty, or inaccurate disaggregated outputs, as exemplified hereafter:

• Selecting input_type=Cumulative and energy_vectors=Electricity to disaggregate monthly totals of electricity consumption will return "0" values as a disaggregated output, on a monthly basis
• Selecting input_type=Cumulative and energy_vectors=Natural gas and electricity to disaggregate monthly totals of electricity consumption will return empty values as a disaggregated output, on a monthly basis
• Selecting input_type=Cumulative and energy_vectors=Electricity to disaggregate cumulative energy consumption timeseries for electricity and natural gas will return inaccurate disaggregated electricity consumption values as an output, on both a monthly and annual basis

Try it out

To use the Disaggregation Engine, please click here

Contact Us

Please contact the PI team if there are any issues by emailing pit@iesve.com