Appliance Events

These reports correspond to a data feed that describes an appliance-level breakdown of electricity consumption for each customer for each calendar day. Thus, the customer can have an overview of the electricity consumption attributed to each appliance installed in the household, understanding its consumption behavior impact and how appliances operation affects the electricity bill.

The report includes two appliance events: (a) non-time based and (b) time-based events.

Non-time Based (NTB) events correspond to appliances operating throughout the day or having multiple switch-on events during the day, so identifying and reporting each one would not be convenient for reporting. Thus, the energy consumption is aggregated daily, in kWh, and the start and stop timestamps of the events are set to the beginning and the end of the day under examination.

On the other hand,Time Based (TB) events are mapped to appliances whose operation can be pinpointed at specific periods of the day using analytical methods, such as Washing Machine or Dishwasher appliance events. These events have specific start and stop timestamps and the energy usage corresponding to each specific event in kWh.

It is important to mention that not all of the existing electrical appliances are supported since (a) there are low-consumption appliances, with minimal participation in the daily consumption, that are nearly impossible to detect in that sampling granularity and (b) there are a lot of specific appliances with low penetration to the market. Thus, NET2GRID NILM Service focuses on the energy-intensive appliances found in most installations and participates heavily in the overall energy consumption. The appliances that are currently supported are the following:

A/AAppliance Event TypeAppliance Event Report KeyType of EventsDisaggregation Category (Activity)Corresponding Appliances (Profile)
1Always OnAlwaysOnNTBAlways On-
2RefrigerationRefrigerationNTBRefrigerationA.01 Fridge,
A.02 Freezer,
A.03 Combi fridge/freezer
3LightingLightingNTBLighting-
4EntertainmentEntertainmentNTBEntertainmentA.14 TV,
A.15 DVD or Blu-ray,
A.16 Digital TV Box,
A.17 Game Console,
A.18 Computer,
A.19 Tablet
5Washing MachineWashingMachineTBLaundryA.11 Washing Machine
6DishwasherDishWasherTBLaundryA.10 Dishwasher
7Tumble DryerDryerTBLaundryA.12 Tumble Dryer
8Oven / Grill / StoveOvenTBCookingA.04 Oven,
A.05 Grill,
A.06 Hob
9Heat PumpsHeatPumpsNTBSpaceHeatingNot applicable to appliances but rather to space heating types:

A.30 Full electric or Hybrid Heat Pump,
SH.04 Heat Pump,
SH.08 Hybrid Heat Pump
10Air ConditionAirConditioningTBSpaceHeatingA.25 Air Conditioning
11Water BoilerWaterBoilerNTBWaterHeatingNot applicable to appliances but rather to water heating types:

WH.02 Electric
12Electric ShowerFlowHeaterTBWaterHeatingA.20 Electric Shower
13Immersion HeaterImmersionHeaterTBWaterHeatingA.24 Immersion Heater
14Electric VehicleElectricVehicleTBElectricVehicleA.21 EV Charger
15Solar ProductionSolarProductionNTBProductionNot applicable to appliances but rather to the Photovoltaic attributes:

SOL.01 Yes,
SOL.02 No

It should be noted that the Always On, Refrigeration, Lighting, and Entertainment (Non-Time Based) appliance events contain the aggregated consumption of all the appliances that participate in each activity daily.

Fetching Appliance Events for a given day

The Get daily appliance events CE API endpoint allows developers to retrieve all the appliance events for a specific day of interest. These appliance event details can then be used within the customer's solution.

A pseudo-code request to the Get daily appliance events endpoint looks like this:

GET /v2/events/daily/{year}/{month}/{day}
Authorization: Bearer <access_token>

A successful request will return a response similar to the following:

{
  "status": "ok",
  "data": {
    "Refrigeration": {
      "Refrigeration": {
        "usage": 0.749,
        "cost": 0.17
      }
    },
    "Always On": {
      "AlwaysOn": {
        "usage": 0.48,
        "cost": 0.1
      }
    },
    "Entertainment": {
      "Entertainment": {
        "usage": 1.261,
        "cost": 0.27
      }
    },
    "Lighting": {
      "Lighting": {
        "usage": 1.1239999999999999,
        "cost": 0.25
      }
    },
    "Production": {
      "SolarProduction": {
        "usage": 0.8280000000000001,
        "cost": 0.18
      }
    },
    "Laundry": {
      "WashingMachine": {
        "usage": 0.015,
        "cost": 0
      }
    },
    "Total": 0.97
  },
  "timestamp": "2022-08-17T08:22:15+02:00",
  "day": "2022-06-02"
}

As you'd probably expect, the response contains the standard JSON structure containing the status field indicating whether or not the response was successful. If successful, the data field will contain a list of appliance events for a specific day. Each message consists of the following properties:

FieldTypeDescription
disaggregation_categoryEnumerationThe disaggregation category that participated in the installation's consumption. The acceptable values of the disaggregation categories (activities) are included in the table above.
appliance_event_report_keyEnumerationThe appliance event report key that participated in the installation's consumption. The acceptable values of the appliance event report keys are included in the table above.
usageFloatIndicates the appliance energy consumption for a specific appliance on the day of interest.
costFloatIndicates the appliance energy consumption cost for a specific appliance on the day of interest.
timestampDateTimeThe date and time the report was created in a YYYY-MM-DDThh:mm:ssTZD format.
dayStringThe day under examination in a YYYY-MM-DD format.

Fetching Appliance Events for a given hour

The Get hourly appliance events CE API endpoint allows developers to retrieve all the appliance events for a specific hour of interest. These appliance event details can then be used within the customer's solution.

A pseudo-code request to the Get hourly appliance events endpoint looks like this:

GET /v2/events/daily/{year}/{month}/{day}/{hour}
Authorization: Bearer <access_token>

A successful request will return a response similar to the following:

{
  "status": "ok",
  "data": {
    "Refrigeration": {
      "Refrigeration": [
        {
          "timestamp_start": "2022-06-01T23:00:00+02:00",
          "timestamp_stop": "2022-06-02T22:59:59+02:00",
          "usage": 0.023,
          "cost": 0.005
        }
      ]
    },
    "Always On": {
      "AlwaysOn": [
        {
          "timestamp_start": "2022-06-01T23:00:00+02:00",
          "timestamp_stop": "2022-06-02T22:59:59+02:00",
          "usage": 0.158,
          "cost": 0.035
        }
      ]
    },
    "Entertainment": {
      "Entertainment": [
        {
          "timestamp_start": "2022-06-01T23:00:00+02:00",
          "timestamp_stop": "2022-06-02T22:59:59+02:00",
          "usage": 0.834,
          "cost": 0.184
        }
      ]
    },
    "Lighting": {
      "Lighting": [
        {
          "timestamp_start": "2022-06-01T23:00:00+02:00",
          "timestamp_stop": "2022-06-02T22:59:59+02:00",
          "usage": 0.169,
          "cost": 0.037
        }
      ]
    },
    "Production": {
      "SolarProduction": [
        {
          "timestamp_start": "2022-06-01T23:00:00+02:00",
          "timestamp_stop": "2022-06-02T22:59:59+02:00",
          "usage": 0.155,
          "cost": 0.034
        }
      ]
    },
    "Total": 0.295
  },
  "timestamp": "2022-08-17T09:28:09+02:00"
}

As you'd probably expect, the response contains the standard JSON structure containing the status field indicating whether or not the response was successful. If successful, the data field will contain a list of appliance events participating in a specific hour of a specific day. Each message consists of the following properties:

FieldTypeDescription
disaggregation_categoryEnumerationThe disaggregation category that participated in the installation's consumption. The acceptable values of the disaggregation categories (activities) are included in the table above.
appliance_event_report_keyEnumerationThe appliance event report key that participated in the installation's consumption. The acceptable values of the appliance event report keys are included in the table above.
timestamp_startStringThe start timestamp for the appliance event contained within the hour of interest under examination in a YYYY-MM-DDThh:mm:ssTZD format.
timestamp_stopStringThe stop timestamp for the appliance event contained within the hour of interest under examination in a YYYY-MM-DDThh:mm:ssTZD format.
usageFloatIndicates the appliance energy consumption for a specific appliance on the appliance event provided.
costFloatIndicates the appliance energy consumption cost for a specific appliance on the appliance event provided.
timestampDateTimeThe date and time the report was created in a YYYY-MM-DDThh:mm:ssTZD format.

Fetching Appliance Events for a given period

The Get period appliance events CE API endpoint allows developers to retrieve all the appliance events for a specific period of interest. These appliance event details can then be used within the customer's solution.

A pseudo-code request to the Get period appliance events endpoint looks like this:

GET /v2/events/summary/{startDate}/{endDate}
Authorization: Bearer <access_token>

It should be mentioned that the start and the end date parameters should be in a yyyy-MM-dd format.

A successful request will return a response similar to the following:

{
  "status": "ok",
  "data": {
    "Refrigeration": {
      "Refrigeration": {
        "count": 3,
        "usage": 0.989,
        "cost": 0.22000000000000003,
        "first_event": "2022-05-31T23:00:00+02:00",
        "last_event": "2022-06-02T23:00:00+02:00"
      }
    },
    "Always On": {
      "AlwaysOn": {
        "count": 3,
        "usage": 0.52,
        "cost": 0.11,
        "first_event": "2022-05-31T23:00:00+02:00",
        "last_event": "2022-06-02T23:00:00+02:00"
      }
    },
    "Entertainment": {
      "Entertainment": {
        "count": 3,
        "usage": 1.865,
        "cost": 0.4,
        "first_event": "2022-05-31T23:00:00+02:00",
        "last_event": "2022-06-02T23:00:00+02:00"
      }
    },
    "Lighting": {
      "Lighting": {
        "count": 3,
        "usage": 2.014,
        "cost": 0.45,
        "first_event": "2022-05-31T23:00:00+02:00",
        "last_event": "2022-06-02T23:00:00+02:00"
      }
    },
    "Production": {
      "SolarProduction": {
        "count": 3,
        "usage": 1.708,
        "cost": 0.37,
        "first_event": "2022-05-31T23:00:00+02:00",
        "last_event": "2022-06-02T23:00:00+02:00"
      }
    },
    "Laundry": {
      "WashingMachine": {
        "count": 3,
        "usage": 1.621,
        "cost": 0.35,
        "first_event": "2022-06-01T12:10:00+02:00",
        "last_event": "2022-06-03T12:10:00+02:00"
      }
    },
    "count": 18,
    "usage": 8.717,
    "cost": 1.9,
    "first_event": "2022-06-01T12:10:00+02:00",
    "last_event": "2022-06-03T12:10:00+02:00"
  },
  "timestamp": "2022-08-17T08:57:11+02:00"
}

As you'd probably expect, the response contains the standard JSON structure containing the status field indicating whether or not the response was successful. If successful, the data field will contain a list of appliance events in the provided period. Each message consists of the following properties:

FieldTypeDescription
disaggregation_categoryEnumerationThe disaggregation category that participated in the installation's consumption. The acceptable values of the disaggregation categories (activities) are included in the table above.
appliance_event_report_keyEnumerationThe appliance event report key that participated in the installation's consumption. The acceptable values of the appliance event report keys are included in the table above.
countIntegerThe number of events included in the provided period.
usageFloatIndicates the appliance energy consumption for a specific appliance on the period of interest.
costFloatIndicates the appliance energy consumption cost for a specific appliance on the period of interest.
first_eventStringThe start timestamp for the first appliance event contained within the period used as input in a YYYY-MM-DDThh:mm:ssTZD format.
last_eventStringThe start timestamp for the last appliance event contained within the period used as input in a YYYY-MM-DDThh:mm:ssTZD format.
timestampDateTimeThe date and time the report was created in a YYYY-MM-DDThh:mm:ssTZD format.

The following screen from the Ynni Mobile App shows how this API call be integrated.