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:

• Store installation profile information allows developers to setup and update the end user's profile.
• Retrieve installation profile information allows developers to display the current installation profile setup of the end user.

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:

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.

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.

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.