Managing installation profile information

Installation profile information is used to improve the accuracy of the NILM services and provide the end-users with more detailed reporting about their energy consumption and is defined in 3 main areas:

  • Installation properties (attributes): The profile attributes provide information about the demographics and layout of the property and energy installation of the end user.
  • Appliances: The list and number of appliances that an end user has in their house.
  • Metadata of appliances: Additional information about specific appliances that can be used to provide better insights and to allow the end user to identify the specific appliance in case there are multiple appliances of this type installed in their house.

In this chapter we will show how to:

The NILM Services provided by NET2GRID support three different profile information options that can be handled to offer versatility to the available profile information.

The client can either choose one of the following options:

Profile Information OptionInstallation Metadata FieldsAppliance Information Fields
Full Profile InformationPostal Code, Country, Property Size, Property Type, Space Heating, Water Heating, Property Age, Number of Occupants, Occupants Type, Photovoltaic, Property Ownership, Space Heating Exchanger Type, Oven Heating Type, Grill Heating Type, Stove Heating TypeRefrigerator, Freezer, Combo Fridge-Freezer, Oven, Grill, Hob, Microwave, Kettle, Toaster, Dishwasher, Washing Machine, Tumble Dryer, Iron, TV, DVD/Bluray, Digital TV Box, Game Console, Computer, Tablet, Electric Vehicle, Electric Shower, Immersion Heater, Air Condition, Swimming Pool, Sauna
Normal Profile InformationPostal Code, Country, Property Size, Property Type, Space Heating, Water Heating, Property Age, Number of Occupants, Occupants Type, Cooking Heating, PhotovoltaicRefrigeration Appliances, Dishwasher, Washing Machine, Tumble Dryer, Oven, Micro-Cooking Appliances, Entertainment Appliances, Electric Vehicle, Electric Shower, Immersion Heater, Air Condition, Swimming Pool, Sauna
Minimal Profile InformationPostal Code, Country, Property Size, Property Type, Space Heating, Water Heating-

The full profile information contains all the installation metadata, demographics, and appliance information currently handled and used by NET2GRID NILM Service. This option takes more time to fill, but it can lead to significantly more accurate and to-the-point analysis and prediction of energy disaggregation. Also, it enables the creation of better and more relevant insight peer groups, which will lead to meaningful comparisons between installations that are very similar.

In the normal profile case, the number of fields that need to be filled is reduced in half. It still contains most of the installation metadata, demographics, and appliance information that can help create pretty accurate models for each customer. This option takes a bit less time to fill in, but it suffers a bit on the accuracy and personalization. However, selecting the remaining fields made taking into consideration the most important aspects of the profile to provide superior NILM services.

In the minimal profile case, the number of fields that need to be filled is set to a minimum. It contains only the barebone of information that needs to be available to provide specialized results and insights, with the minimum possible profile information. This option takes practically no time to fill, but the loss of profile information takes its toll on accuracy and personalization. However, selecting the remaining fields made taking into consideration the most important aspects of the profile to provide superior NILM services.


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 setup profile of an end-user. This means that the call can be performed multiple types with a subset of information based on the screens that are available to the end user and the business logic of the app.

While not all profile attributes are required, a minimum data set is mandatory to ensure the correct functioning of NET2GRID's Insight platform. The minimal required attributes are:

  • Postal code (PropertyLocation): the postal code of the premises.
  • Country (PropertyCountry): the country in which the premises is located. The value should be formatted according to the ISO 3166 alpha-2 country code standard.
  • Property Size (PropertySize): the number of bedrooms in the premises.
  • Property Type (PropertyType): describes the layout of the property.
  • Space/Room heating (SpaceHeating): the type of space heating installed in the premises
  • Water heating (WaterHeating): the type of water heating installed in the premises

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 installation information of an end user:

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

Below there 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",
            "PropertyLocation": "3825AE",
            "PropertyCountry": "NL"
     },
     "Appliances": {}
}

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