Guides

Managing installation profile information

Suggest Edits

Introduction

The installation profile information enhances the accuracy of EnergyAI services and enables more detailed energy consumption reporting for end users. It is categorized into three main areas:

  • Installation properties (attributes): These profile attributes offer insights into the end user's demographics, property layout, and energy installation.
  • Appliances: The number and types of appliances present in an end user's home.
  • Metadata of appliances: Additional details about specific appliances help provide better insights and enable end users to distinguish between multiple appliances of the same type in their home.

In this chapter we will show how to:

To ensure precise energy disaggregation and valuable insights, EnergyAI services depend on a standard profile option. This profile captures key installation metadata and appliance details, balancing ease of input with high accuracy.

The profile details that an end-user needs to complete are as follows:

Profile InformationInstallation Properties FieldsAppliance Information Fields
Standard Profile InformationPostal Code
Country
Property Size
Property Type
Property Age
Number of Occupants
Oven/Stove/Grill Heating
Space Heating
Water Heating
Photovoltaic		Electric Vehicle
Air Condition

The standard profile information includes the essential input required to provide specialized disaggregation results, insights, and recommendations with the minimum amount of profile information. Moreover, the above list constitutes the mandatory profile attributes that the end-user must specify for the account to be considered complete. The corresponding profile completion information can be returned via the relevant API request.

Insights service

By providing the Postal Code, Country, Property Type, Property Age, and Number of Occupants, end-users enable the creation of more relevant peer groups, allowing for meaningful comparisons with similar users. The Insights service is thoroughly described in the Insights chapter.

Recommendations service

Additionally, filling in the Property Type, Property Age, and Property Ownership attributes allows for personalized recommendations that include tips on optimizing appliance use and reducing energy consumption. Find more information regarding the Recommendation reports in the Recommendations chapter.

NILM Disaggregation

Declaring the Space Heating, Water Heating, Photovoltaic, and Oven/Stove/Grill Heatting attributes, along with Electric Vehicle and Air Condition appliances, enables the creation of accurate models for the most energy-intensive categories. However, by selecting the remaining fields (including appliance metadata), the full functionality of NILM services can be unlocked. The Disaggregation Categories' full description, and more information regarding energy disaggregation, are presented in the respective NILM/ Energy Disaggregationchapter.

Setting installation profile information

To allow end users to give the information about their installation CE API provides the POST /v2/profile/attributes endpoint.

📘

The endpoint performs delta updates on the currently configured profile of an end user. This means the call can be made multiple times with a subset of information, depending on the screens available to the end user and the app's business logic.

Although EnergyAI Service can manage and utilize a wide range of profile attributes, the mandatory set outlined in the standard profile information is essential for the proper operation of NILM services. The required attributes are:

  • Postal code (PropertyLocation): the postal code of the premises.
  • Country (PropertyCountry): the country in which the premises are located. The value should be formatted according to the ISO 3166 alpha-2 country code standard.
  • Property Size (PropertySize): the number of bedrooms on the premises.
  • Property Type (PropertyType): describes the layout of the premises.
  • Property Age (PropertyAge): represents the period during which the premise was built.
  • Number of Occupants (Occupants): indicates the number of people living on the premises.
  • Oven/Stove/Grill heating (OvenHeating/StoveHeating/GrillHeating): the type of cooking (oven/stove/grill) appliances installed on the premises
  • Space heating (SpaceHeating): the type of space heating installed on the premises.
  • Water heating (WaterHeating): the type of water heating installed on the premises.
  • Photovoltaic (Photovoltaic): indicates the presence of Photovoltaic (solar) panels on the premises.

❗️

For the cooking activity, only the most relevant appliance type for the user (oven, stove, or grill) is required for the cooking disaggregation category to be enabled.

  • STH.02 should be used for users eqquiped with an electric-sourced stove.
  • GH.02 should be used for users eqquiped with an electric-sourced grill.
  • OH.02 should be used for users eqquiped with an electric-sourced oven

A complete overview of all the attributes can be found in the Allowed values for setting up installation profile information chapter.

CE-API provides the following endpoint for setting the installation information of an end user:

POST /v2/profile/attributes
Authorization: Bearer <access_token>

Below is an example of the request body of the call for setting up the mandatory profile attributes of an end user:

{
     "Attributes": {
            "SpaceHeating": "SH.01",
            "WaterHeating": "WH.01",
            "PropertyType": "PT.01",
            "PropertySize": "PS.04",
         	  "PropertyAge": "PA.02",
            "PropertyLocation": "3825AE",
            "PropertyCountry": "NL",
       			"Occupants": "OCC.01",
         	  "Photovoltaic": "SOL.01",
            "StoveHeating": "STH.00",
            "GrillHeating": "GH.01",
            "OvenHeating": "OH.00",     
     },
     "Appliances": { 
       "A.21": 1,
       "A.25": 2}
}

Below is another request body example with more information provided, and multiple selections under space & water heating:

{
  "Attributes": {
    "PropertyLocation": "52100",
    "PropertyCountry": "GR",
    "PropertySize": "PS.04",
    "PropertyType": "PT.01",
    "PropertyAge": "PA.02",
    "Ownership": "OWN.01",
    "Occupants": "OCC.01",
    "OccupantType": "OT.01",
    "SpaceHeating": "SH.01,SH.02,SH.05",
    "WaterHeating": "WH.06,WH.07",
    "StoveHeating": "STH.00",
    "GrillHeating": "GH.01",
    "OvenHeating": "OH.00",
    "SpaceHeatingExchangerType": "SHET.01",
    "Photovoltaic": "SOL.01"
  },
  "Appliances": {
    "A.01": 1,
    "A.02": 1,
    "A.03": 1,
    "A.04": 1,
    "A.05": 3,
    "A.06": 1,
    "A.07": 1,
    "A.08": 2,
    "A.09": 1,
    "A.10": 2,
    "A.11": 1,
    "A.12": 1,
    "A.13": 2,
    "A.14": 1,
    "A.15": 1,
    "A.16": 1,
    "A.17": 1,
    "A.18": 1,
    "A.19": 2,
    "A.20": 1,
    "A.21": 1,
    "A.22": 1,
    "A.23": 1,
    "A.24": 1,
    "A.25": 1,
    "A.26": 1,
    "A.27": 2,
    "A.28": 1,
    "A.29": 1,
    "A.30": 2
  },
  "ApplianceMetadata": {
    "A.10": [
      {
        "description": "basement",
        "id": "8b46ed4cc7945bd9",
        "applianceAge": "AA.03",
        "applianceType": "DT.02",
        "applianceVolume": "AV.01",
        "brand": "Bosch"
      },
      {
        "description": "main-floor",
        "id": "665ads65ad565",
        "applianceAge": "AA.01",
        "applianceType": "DT.01",
        "applianceVolume": "AV.01",
        "brand": "Bosch"
      }
    ],
    "A.11": [
      {
        "description": "1st floor",
        "id": "0991b544386a6038",
        "applianceAge": "AA.03",
        "applianceType": "WT.01",
        "applianceVolume": "AV.02",
        "brand": "Bosch"
      }
    ],
    "A.29": [
      {
        "description": "Battery Energy Storage System",
        "id": "8881b544386a6039",
        "batterySize": "5"
      }
    ],
    "A.30": [
      {
        "description": "1st floor",
        "id": "d23ed23ed243eefd3",
        "applianceType": "air-to-air",
        "applianceSetup": "full-electric"
      },
      {
        "description": "2nd floor",
        "id": "d23ed23ed243eefd4",
        "applianceType": "air-to-water",
        "applianceSetup": "hybrid"
      }
    ]
  }
}

As shown in the example, the Post profile attributes endpoint accepts an Attributes, Appliances and optionally an ApplianceMetadata object. The values for all these parameters are coded and the complete overview of all codes can be found in the Allowed values for setting up installation profile information chapter.

🚧

Always provide the full list of allowed appliances when saving the profile attributes. Use the value 0, if the end-user indicated they don't own that particular appliance.

Below, a few screenshot examples of how the Ynni app handles the installation profile setup.

Example showing input screen for appliance management on the left, Space Heating and Cooling selection in the middle and Photovoltaic setup on the right.

Example showing the input screen for appliance management on the left, Space Heating and Cooling selection in the middle, and Photovoltaic setup on the right.

Setting up appliance metadata

The ApplianceMetadata parameter is used to supply metadata for the configured appliances. This parameter is optional, however supplying additional metadata can be very clarifying to end-users when presented with reports, especially when dealing with multiple appliances of the same type. Details on which metadata parameters are allowed per appliance type are available through the Get appliance definitions endpoint that is described in the next chapter.

Below are a few screenshot examples of how the Ynni app handles the appliance metadata setup.

Example showing input screen for appliance selection on the left and the setting of the appliances metadata on the right.

Example showing input screen for appliance selection on the left and the setting of the appliances metadata on the right.


Retrieving installation profile information

The NET2GRID's CE-API provides the GET /v2/profile/attributes endpoint which can be used to request the profile attributes information that is currently known for the end user. This is very useful to provide the end-user with an overview of all profile information the NET2GRID's INSIGHT Platform uses to train the Non-Intrusive Load Monitoring services.

The request to get the current profile attributes looks like this:

GET /v2/profile/attributes
Authorization: Bearer <access_token>

If executed successfully the response will look similar to this (depending on the amount of information that has been setup in the profile of an end user):

{
    "status": "ok",
    "data": {
        "Attributes": {
            "GrillHeating": "GH.02",
            "Occupants": "OCC.03",
            "OccupantType": "OT.02",
            "OvenHeating": "OH.02",
            "Ownership": "OWN.01",
            "Photovoltaic": "SOL.01",
            "PropertyAge": "PA.02",
            "PropertySize": "PS.03",
            "PropertyType": "PT.04",
            "SpaceHeating": "SH.01",
            "StoveHeating": "STH.01",
            "WaterHeating": "WH.01",
            "PropertyLocation": "3703 HR",
            "PropertyCountry": "NL"
        },
        "Appliances": {
            "A.01": 1,
            "A.02": 0,
            "A.03": 1,
            "A.04": 1,
            "A.05": 0,
            "A.06": 1,
            "A.07": 1,
            "A.08": 0,
            "A.09": 0,
            "A.10": 1,
            "A.11": 1,
            "A.12": 0,
            "A.13": 1,
            "A.14": 1,
            "A.15": 1,
            "A.16": 0,
            "A.17": 0,
            "A.18": 0,
            "A.19": 0,
            "A.20": 0,
            "A.21": 1,
            "A.22": 0,
            "A.23": 1,
            "A.24": 0,
            "A.25": 0,
            "A.26": 0,
            "A.27": 0,
            "A.28": 0,
            "A.29": 0,
            "A.30":0
        },
        "ApplianceMetadata": {
            "A.01": [
                {
                    "description": "Refrigeration2",
                    "id": "FAB87EAC-D424-4243-BB25-81E15FE4EE6C",
                    "applianceType": "FR.09"
                }
            ],
            "A.03": [
                {
                    "description": "Combi fridge",
                    "id": "DB889828-FB0B-48A5-84E8-17BB3342B6B1"
                }
             ],
            "A.04": [
                {
                    "description": "Oven",
                    "id": "46652a8b-46c1-4300-aecc-977b947e5bed"
                }
            ],
            "A.07": [
                {
                    "description": "Microwave",
                    "id": "2bc6793df1124a46b724cbc68af42fd8"
                }
            ],
            "A.10": [
                {
                    "description": "dishwasher",
                    "id": "9c50aa1b-bcef-49b7-bed0-1305ebdc45d5"
                }
            ],
            "A.11": [
                {
                    "description": "Washing machine",
                    "id": "1181a22a-ed29-4ad2-8cb0-49589416613b"
                }
            ],
            "A.13": [
                {
                    "description": "Iron",
                    "id": "2E2A5C2D-5CCD-418C-832F-602FC3134355"
                }
            ],
            "A.15": [
                {
                    "description": "DVD or Bluray",
                    "id": "f20398fd-dd73-4a19-b179-e07657baf1de"
                }
            ],
            "A.23": [
                {
                    "description": "Sauna",
                    "id": "c30975ef-679e-438b-a3cb-fc02d50d956a"
                }
            ]
        }
    }
}

The status attribute signals that the request was executed successfully. The data attribute contains instances of the Attributes, Appliances and ApplianceMetadata objects describing the profile attributes known by the NET2GRID's INSIGHT Platform for the end user.
The data structure is the same as when saving installation profile information and the meaning for each property code can be found in the Allowed values for setting up installation profile information chapter.

Updated 4 days ago

What’s Next