UsageHistory

Get All Usage Hours with DeviceId (Energy devices)

GET

http://localhost:8080

/api/usage-history/hour/{deviceId}

Get All Usage Hours with DeviceId (Energy devices) › path Parameters

deviceId

string · required

Get All Usage Hours with DeviceId (Energy devices) › Responses

Return all usage hours for energy devices (PLUG/MCB).

UsageHistoryHour[]

UsageHistoryHour

_id

string · required

Primary ID of the UsageHistoryHour

Example: 64b7f1e6f9c9d4e5b8a9f7c3

hour

number · required

No. What Hour (E.g. 7 means 0700 - 0800)

Example: 7

onStatus

string · enum · required

Status of the Plug (ON / OFF)

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

deviceType

string · enum · required

Type of device (PLUG, MCB, etc.)

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

Example: PLUG

createdAt

string · date-time · required

Date Time of the Creation

Example: 2021-09-01

updatedAt

string · date-time · required

Date Time of the Update

Example: 2021-09-01

actualDate

string · date-time · required

Date Time of the Update

Example: 2021-09-01

macId

string · required

MAC ID of the device

Example: 1092384701928347

device

string · required

Reference to the device

Example: 64b7f1e6f9c9d4e5b8a9f7c3

wifiStrength

number

WiFi signal strength at the time of the hourly record

Example: -65

GET/api/usage-history/hour/{deviceId}

curl http://localhost:8080/api/usage-history/hour/:deviceId

Example Responses

[
  {
    "_id": "64b7f1e6f9c9d4e5b8a9f7c3",
    "hour": "7",
    "onStatus": "ON",
    "deviceType": "PLUG",
    "createdAt": "2021-09-01",
    "updatedAt": "2021-09-01",
    "actualDate": "2021-09-01",
    "macId": "1092384701928347",
    "wifiStrength": -65,
    "device": "64b7f1e6f9c9d4e5b8a9f7c3"
  }
]

application/json

Get Usage Hours for a Specific Date and Device

GET

http://localhost:8080

/api/usage-history/hour/date/{deviceId}

Get Usage Hours for a Specific Date and Device › path Parameters

deviceId

string · required

Get Usage Hours for a Specific Date and Device › query Parameters

from

string · required

till

string · required

Get Usage Hours for a Specific Date and Device › Responses

Returns usage hours for a specific device and date.

UsageHistoryHour[]

UsageHistoryHour

_id

string · required

Primary ID of the UsageHistoryHour

Example: 64b7f1e6f9c9d4e5b8a9f7c3

hour

number · required

No. What Hour (E.g. 7 means 0700 - 0800)

Example: 7

onStatus

string · enum · required

Status of the Plug (ON / OFF)

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

deviceType

string · enum · required

Type of device (PLUG, MCB, etc.)

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

Example: PLUG

createdAt

string · date-time · required

Date Time of the Creation

Example: 2021-09-01

updatedAt

string · date-time · required

Date Time of the Update

Example: 2021-09-01

actualDate

string · date-time · required

Date Time of the Update

Example: 2021-09-01

macId

string · required

MAC ID of the device

Example: 1092384701928347

device

string · required

Reference to the device

Example: 64b7f1e6f9c9d4e5b8a9f7c3

wifiStrength

number

WiFi signal strength at the time of the hourly record

Example: -65

GET/api/usage-history/hour/date/{deviceId}

curl 'http://localhost:8080/api/usage-history/hour/date/:deviceId?from=<string>&till=<string>'

Example Responses

[
  {
    "_id": "64b7f1e6f9c9d4e5b8a9f7c3",
    "hour": "7",
    "onStatus": "ON",
    "deviceType": "PLUG",
    "createdAt": "2021-09-01",
    "updatedAt": "2021-09-01",
    "actualDate": "2021-09-01",
    "macId": "1092384701928347",
    "wifiStrength": -65,
    "device": "64b7f1e6f9c9d4e5b8a9f7c3"
  }
]

application/json

Get Usage Days for a Specific Device (Energy devices)

GET

http://localhost:8080

/api/usage-history/day/{deviceId}

Get Usage Days for a Specific Device (Energy devices) › path Parameters

deviceId

string · required

Get Usage Days for a Specific Device (Energy devices) › Responses

Returns usage days for energy devices (PLUG/MCB).

UsageHistoryDay[]

UsageHistoryDay

_id

string · required

Primary ID of the UsageHistoryDay

Example: 64b7f1e6f9c9d4e5b8a9f7c3

UsageHistoryHour[] · required

Usage History of the device (Hourly)

createdAt

string · date-time · required

Date Time of the Creation

Example: 2021-09-01

updatedAt

string · date-time · required

Date Time of the Update

Example: 2021-09-01

deviceType

string · enum · required

Type of device (PLUG, MCB, etc.)

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

Example: PLUG

macId

string · required

MAC ID of the device

Example: 1092384701928347

device

string · required

Reference to the device

Example: 64b7f1e6f9c9d4e5b8a9f7c3

GET/api/usage-history/day/{deviceId}

curl http://localhost:8080/api/usage-history/day/:deviceId

Example Responses

[
  {
    "_id": "64b7f1e6f9c9d4e5b8a9f7c3",
    "usageHistoryHourly": [
      {
        "_id": "64b7f1e6f9c9d4e5b8a9f7c3",
        "hour": "7",
        "onStatus": "ON",
        "deviceType": "PLUG",
        "createdAt": "2021-09-01",
        "updatedAt": "2021-09-01",
        "actualDate": "2021-09-01",
        "macId": "1092384701928347",
        "wifiStrength": -65,
        "device": "64b7f1e6f9c9d4e5b8a9f7c3"
      }
    ],
    "createdAt": "2021-09-01",
    "updatedAt": "2021-09-01",
    "deviceType": "PLUG",
    "macId": "1092384701928347",
    "device": "64b7f1e6f9c9d4e5b8a9f7c3"
  }
]

application/json

Get Usage for a system using a Specific Date

GET

http://localhost:8080

/api/usage-history/date/system-id/{systemId}

Get Usage for a system using a Specific Date › path Parameters

systemId

string · required

Get Usage for a system using a Specific Date › query Parameters

date

string · required

Get Usage for a system using a Specific Date › Responses

Returns usage for a system and date.

UsageHistoryHour[]

UsageHistoryHour

_id

string · required

Primary ID of the UsageHistoryHour

Example: 64b7f1e6f9c9d4e5b8a9f7c3

hour

number · required

No. What Hour (E.g. 7 means 0700 - 0800)

Example: 7

onStatus

string · enum · required

Status of the Plug (ON / OFF)

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

deviceType

string · enum · required

Type of device (PLUG, MCB, etc.)

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

Example: PLUG

createdAt

string · date-time · required

Date Time of the Creation

Example: 2021-09-01

updatedAt

string · date-time · required

Date Time of the Update

Example: 2021-09-01

actualDate

string · date-time · required

Date Time of the Update

Example: 2021-09-01

macId

string · required

MAC ID of the device

Example: 1092384701928347

device

string · required

Reference to the device

Example: 64b7f1e6f9c9d4e5b8a9f7c3

wifiStrength

number

WiFi signal strength at the time of the hourly record

Example: -65

GET/api/usage-history/date/system-id/{systemId}

curl 'http://localhost:8080/api/usage-history/date/system-id/:systemId?date=<string>'

Example Responses

[
  {
    "_id": "64b7f1e6f9c9d4e5b8a9f7c3",
    "hour": "7",
    "onStatus": "ON",
    "deviceType": "PLUG",
    "createdAt": "2021-09-01",
    "updatedAt": "2021-09-01",
    "actualDate": "2021-09-01",
    "macId": "1092384701928347",
    "wifiStrength": -65,
    "device": "64b7f1e6f9c9d4e5b8a9f7c3"
  }
]

application/json

Get Energy Usage for a system within a date range.

GET

http://localhost:8080

/api/usage-history/date-range/system/{systemId}

Get Energy Usage for a system within a date range. › path Parameters

systemId

string · required

Get Energy Usage for a system within a date range. › query Parameters

from

string · required

till

string · required

Get Energy Usage for a system within a date range. › Responses

Returns a list of energy usage with cost for the last X days for a system.

UsageHistoryDayWithCostBreakdownDto[]

UsageHistoryDayWithCostBreakdownDto

date

string · required

No. Hour of the Usage History

Example: 2023-03-15

totalEnergyUsage

number · required

Total Energy Usage in a Day (kWh)

Example: 12.48

cost

number · required

Energy cost for this day in dollars. Zero (0) if no tariff rate is configured for this day.

Example: 23.1

tariffRate

number | null

Tariff rate applied for this day in cents per kWh/L. Null if no tariff rate is configured.

Example: 10

GET/api/usage-history/date-range/system/{systemId}

curl 'http://localhost:8080/api/usage-history/date-range/system/:systemId?from=<string>&till=<string>'

Example Responses

[
  {
    "date": "2023-03-15",
    "totalEnergyUsage": 12.48,
    "cost": 23.1,
    "tariffRate": 10
  }
]

application/json

Get Accumulated Energy Usage across all systems within a date range

GET

http://localhost:8080

/api/usage-history/date-range/accumulated

Returns aggregated energy usage data for all systems combined, summed up by day. This endpoint provides platform-wide energy consumption statistics. Optionally filter by device type (PLUG, MCB, IAQ_SENSOR). Requires SUPERADMIN or ADMIN role.

Get Accumulated Energy Usage across all systems within a date range › query Parameters

from

string · required

till

string · required

Get Accumulated Energy Usage across all systems within a date range › Responses

Accumulated usage data retrieved successfully

UsageHistoryDayBreakdownDto[]

UsageHistoryDayBreakdownDto

date

string · required

No. Hour of the Usage History

Example: 2023-03-15

totalEnergyUsage

number · required

Total Energy Usage in a Day (kWh)

Example: 12.48

GET/api/usage-history/date-range/accumulated

curl 'http://localhost:8080/api/usage-history/date-range/accumulated?from=<string>&till=<string>'

Example Responses

[
  {
    "date": "2023-03-15",
    "totalEnergyUsage": 12.48
  }
]

application/json

Get Energy Usage for a tenant within a date range

GET

http://localhost:8080

/api/usage-history/date-range/tenant/{tenantId}

Get Energy Usage for a tenant within a date range › path Parameters

tenantId

string · required

Get Energy Usage for a tenant within a date range › query Parameters

from

string · required

till

string · required

Get Energy Usage for a tenant within a date range › Responses

Returns a list of energy usage with cost for a tenant within a date range.

UsageHistoryDayWithCostBreakdownDto[]

UsageHistoryDayWithCostBreakdownDto

date

string · required

No. Hour of the Usage History

Example: 2023-03-15

totalEnergyUsage

number · required

Total Energy Usage in a Day (kWh)

Example: 12.48

cost

number · required

Energy cost for this day in dollars. Zero (0) if no tariff rate is configured for this day.

Example: 23.1

tariffRate

number | null

Tariff rate applied for this day in cents per kWh/L. Null if no tariff rate is configured.

Example: 10

GET/api/usage-history/date-range/tenant/{tenantId}

curl 'http://localhost:8080/api/usage-history/date-range/tenant/:tenantId?from=<string>&till=<string>'

Example Responses

[
  {
    "date": "2023-03-15",
    "totalEnergyUsage": 12.48,
    "cost": 23.1,
    "tariffRate": 10
  }
]

application/json

Get Energy Usage for a zone within a date range

GET

http://localhost:8080

/api/usage-history/date-range/zone/{zoneId}

Get Energy Usage for a zone within a date range › path Parameters

zoneId

string · required

Get Energy Usage for a zone within a date range › query Parameters

from

string · required

till

string · required

Get Energy Usage for a zone within a date range › Responses

Returns a list of energy usage with cost for a zone within a date range.

UsageHistoryDayWithCostBreakdownDto[]

UsageHistoryDayWithCostBreakdownDto

date

string · required

No. Hour of the Usage History

Example: 2023-03-15

totalEnergyUsage

number · required

Total Energy Usage in a Day (kWh)

Example: 12.48

cost

number · required

Energy cost for this day in dollars. Zero (0) if no tariff rate is configured for this day.

Example: 23.1

tariffRate

number | null

Tariff rate applied for this day in cents per kWh/L. Null if no tariff rate is configured.

Example: 10

GET/api/usage-history/date-range/zone/{zoneId}

curl 'http://localhost:8080/api/usage-history/date-range/zone/:zoneId?from=<string>&till=<string>'

Example Responses

[
  {
    "date": "2023-03-15",
    "totalEnergyUsage": 12.48,
    "cost": 23.1,
    "tariffRate": 10
  }
]

application/json

Get Energy Usage for a room within a date range

GET

http://localhost:8080

/api/usage-history/date-range/room/{roomId}

Get Energy Usage for a room within a date range › path Parameters

roomId

string · required

Get Energy Usage for a room within a date range › query Parameters

from

string · required

till

string · required

Get Energy Usage for a room within a date range › Responses

Returns a list of energy usage with cost for the last X days for a room.

UsageHistoryDayWithCostBreakdownDto[]

UsageHistoryDayWithCostBreakdownDto

date

string · required

No. Hour of the Usage History

Example: 2023-03-15

totalEnergyUsage

number · required

Total Energy Usage in a Day (kWh)

Example: 12.48

cost

number · required

Energy cost for this day in dollars. Zero (0) if no tariff rate is configured for this day.

Example: 23.1

tariffRate

number | null

Tariff rate applied for this day in cents per kWh/L. Null if no tariff rate is configured.

Example: 10

GET/api/usage-history/date-range/room/{roomId}

curl 'http://localhost:8080/api/usage-history/date-range/room/:roomId?from=<string>&till=<string>'

Example Responses

[
  {
    "date": "2023-03-15",
    "totalEnergyUsage": 12.48,
    "cost": 23.1,
    "tariffRate": 10
  }
]

application/json

Get Energy Usage for a distribution box within a date range

GET

http://localhost:8080

/api/usage-history/date-range/distribution-box/{distributionBoxId}

Get Energy Usage for a distribution box within a date range › path Parameters

distributionBoxId

string · required

Get Energy Usage for a distribution box within a date range › query Parameters

from

string · required

till

string · required

Get Energy Usage for a distribution box within a date range › Responses

Returns a list of daily energy usage with cost for a distribution box.

UsageHistoryDayWithCostBreakdownDto[]

UsageHistoryDayWithCostBreakdownDto

date

string · required

No. Hour of the Usage History

Example: 2023-03-15

totalEnergyUsage

number · required

Total Energy Usage in a Day (kWh)

Example: 12.48

cost

number · required

Energy cost for this day in dollars. Zero (0) if no tariff rate is configured for this day.

Example: 23.1

tariffRate

number | null

Tariff rate applied for this day in cents per kWh/L. Null if no tariff rate is configured.

Example: 10

GET/api/usage-history/date-range/distribution-box/{distributionBoxId}

curl 'http://localhost:8080/api/usage-history/date-range/distribution-box/:distributionBoxId?from=<string>&till=<string>'

Example Responses

[
  {
    "date": "2023-03-15",
    "totalEnergyUsage": 12.48,
    "cost": 23.1,
    "tariffRate": 10
  }
]

application/json

Get daily energy usage for a device within a date range

GET

http://localhost:8080

/api/usage-history/date-range/device/{deviceId}

Get daily energy usage for a device within a date range › path Parameters

deviceId

string · required

Get daily energy usage for a device within a date range › query Parameters

from

string · required

till

string · required

Get daily energy usage for a device within a date range › Responses

200

Daily usage breakdown with cost for the device.

UsageHistoryDayWithCostBreakdownDto[]

UsageHistoryDayWithCostBreakdownDto

date

string · required

No. Hour of the Usage History

Example: 2023-03-15

totalEnergyUsage

number · required

Total Energy Usage in a Day (kWh)

Example: 12.48

cost

number · required

Energy cost for this day in dollars. Zero (0) if no tariff rate is configured for this day.

Example: 23.1

tariffRate

number | null

Tariff rate applied for this day in cents per kWh/L. Null if no tariff rate is configured.

Example: 10

GET/api/usage-history/date-range/device/{deviceId}

curl 'http://localhost:8080/api/usage-history/date-range/device/:deviceId?from=<string>&till=<string>'

Example Responses

[
  {
    "date": "2023-03-15",
    "totalEnergyUsage": 12.48,
    "cost": 23.1,
    "tariffRate": 10
  }
]

application/json

Get Usage for a system using a Specific Date Range

GET

http://localhost:8080

/api/usage-history/date-range/system-id/{systemId}

Get Usage for a system using a Specific Date Range › path Parameters

systemId

string · required

Get Usage for a system using a Specific Date Range › query Parameters

from

string · required

till

string · required

Get Usage for a system using a Specific Date Range › Responses

200

Returns usage for a system and date.

number[]

GET/api/usage-history/date-range/system-id/{systemId}

curl 'http://localhost:8080/api/usage-history/date-range/system-id/:systemId?from=<string>&till=<string>'

Example Responses

[
  0
]

application/json

Get hourly usage for a device (Plug/MCB) within a date range with current tariff rate

GET

http://localhost:8080

/api/usage-history/date-range/device-id/{deviceId}

Returns hourly usage breakdown and the current tariff rate for cost calculations.

Get hourly usage for a device (Plug/MCB) within a date range with current tariff rate › path Parameters

deviceId

string · required

Get hourly usage for a device (Plug/MCB) within a date range with current tariff rate › query Parameters

from

string · required

till

string · required

Get hourly usage for a device (Plug/MCB) within a date range with current tariff rate › Responses

200

Returns hourly usage data and current tariff rate for a device.

UsageHistoryHourWithTariffResponseDto

UsageHistoryHourBreakdownDto[] · required

Array of hourly usage data

Example: [{"hour":0,"totalEnergyUsage":1.2},{"hour":1,"totalEnergyUsage":1.5}]

currentTariffRate

number | null

Current tariff rate in cost per kWh. Null if no tariff rate is configured. Useful for frontend calculations.

Example: 0.25

GET/api/usage-history/date-range/device-id/{deviceId}

curl 'http://localhost:8080/api/usage-history/date-range/device-id/:deviceId?from=<string>&till=<string>'

Example Responses

{
  "data": [
    {
      "hour": 0,
      "totalEnergyUsage": 1.2
    },
    {
      "hour": 1,
      "totalEnergyUsage": 1.5
    }
  ],
  "currentTariffRate": 0.25
}

application/json

Get Energy Usage for energy devices (RealTime) using a Specific Date Range (MCB, Plug only)

GET

http://localhost:8080

/api/usage-history/date-range/realTime/energy/device-id/{deviceId}

Returns real-time energy usage data including power, current, voltage, and power factor for PLUG and MCB devices.

Get Energy Usage for energy devices (RealTime) using a Specific Date Range (MCB, Plug only) › path Parameters

deviceId

string · required

Get Energy Usage for energy devices (RealTime) using a Specific Date Range (MCB, Plug only) › query Parameters

from

string · required

till

string · required

Get Energy Usage for energy devices (RealTime) using a Specific Date Range (MCB, Plug only) › Responses

200

Real-time energy usage data for MCB or Plug devices within date range

UsageHistoryEnergyRealtimeDto[]

UsageHistoryEnergyRealtimeDto

onStatus

string · enum · required

Status of the device (ON / OFF)

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

createdAt

string · date-time · required

Date Time of the Creation

Example: 2021-09-01T00:00:00.000Z

current

number · required

Current in Amperes (A)

Example: 2.5

voltage

number · required

Voltage in Volts (V)

Example: 230

powerFactor

number · required

Power factor (0-1)

Example: 0.9

power

number · required

Power in Watts (W)

Example: 517.5

GET/api/usage-history/date-range/realTime/energy/device-id/{deviceId}

curl 'http://localhost:8080/api/usage-history/date-range/realTime/energy/device-id/:deviceId?from=<string>&till=<string>'

Example Responses

[
  {
    "onStatus": "ON",
    "createdAt": "2021-09-01T00:00:00.000Z",
    "current": 2.5,
    "voltage": 230,
    "powerFactor": 0.9,
    "power": 517.5
  }
]

application/json

Get summed realtime power for all MCBs in a room

GET

http://localhost:8080

/api/usage-history/date-range/realTime/room/{roomId}/mcb

Returns the aggregated total power for all MCB devices in the specified room within the given date range.

Get summed realtime power for all MCBs in a room › path Parameters

roomId

string · required

Get summed realtime power for all MCBs in a room › query Parameters

from

string · required

till

string · required

Get summed realtime power for all MCBs in a room › Responses

200

Summed realtime power for all MCBs in the room.

McbRoomRealtimeResponseDto

McbRealtimeSeriesDto[] · required

One time-series per MCB measurement type found in the room, plus a COMBINED series that sums all types

GET/api/usage-history/date-range/realTime/room/{roomId}/mcb

curl 'http://localhost:8080/api/usage-history/date-range/realTime/room/:roomId/mcb?from=<string>&till=<string>'

Example Responses

{
  "series": [
    {
      "measurementType": "SSO",
      "data": [
        {
          "createdAt": "2024-08-25T15:00:00Z",
          "power": 200
        }
      ],
      "max": 500,
      "average": 250
    }
  ]
}

application/json

AI insight on what devices are in a room based on MCB data

GET

http://localhost:8080

/api/usage-history/room/{roomId}/mcb/ai-insight

Analyses 7 days of hourly MCB circuit data and 48 hours of realtime spikes to predict what electrical devices are likely present in the room.

AI insight on what devices are in a room based on MCB data › path Parameters

roomId

string · required

AI insight on what devices are in a room based on MCB data › Responses

200

AI-generated device prediction for the room.

RoomMcbAiInsightResponseDto

summary

string · required

One-liner summary of room energy behaviour

Example: This room shows signs of an overnight portable AC and a mini fridge drawing constant baseline power.

RoomMcbAiInsightPossibleDeviceDto[] · required

List of predicted devices and why

GET/api/usage-history/room/{roomId}/mcb/ai-insight

curl http://localhost:8080/api/usage-history/room/:roomId/mcb/ai-insight

Example Responses

{
  "summary": "This room shows signs of an overnight portable AC and a mini fridge drawing constant baseline power.",
  "possibleDevices": [
    {
      "device": "Portable AC",
      "reason": "600–900W continuously from 10pm–8am on SSO circuit"
    }
  ]
}

application/json

Get Idle Energy Usage for a device (RealTime) using a Specific Date Range

GET

http://localhost:8080

/api/usage-history/date-range/realTime/idle-energy/device-id/{deviceId}

Get Idle Energy Usage for a device (RealTime) using a Specific Date Range › path Parameters

deviceId

string · required

Get Idle Energy Usage for a device (RealTime) using a Specific Date Range › query Parameters

from

string · required

till

string · required

Get Idle Energy Usage for a device (RealTime) using a Specific Date Range › Responses

200

Returns idle energy (RT) for a device.

DeviceEnergyDto

energy

number · required

Total energy consumed by the device in watt-hours.

Example: 231

GET/api/usage-history/date-range/realTime/idle-energy/device-id/{deviceId}

curl 'http://localhost:8080/api/usage-history/date-range/realTime/idle-energy/device-id/:deviceId?from=<string>&till=<string>'

Example Responses

{
  "energy": 231
}

application/json

Get Average Energy Usage for a device (RealTime) using a Specific Date Range

GET

http://localhost:8080

/api/usage-history/date-range/realTime/average-energy/device-id/{deviceId}

Get Average Energy Usage for a device (RealTime) using a Specific Date Range › path Parameters

deviceId

string · required

Get Average Energy Usage for a device (RealTime) using a Specific Date Range › query Parameters

from

string · required

till

string · required

Get Average Energy Usage for a device (RealTime) using a Specific Date Range › Responses

200

Returns average energy (RT) for a device.

DeviceEnergyDto

energy

number · required

Total energy consumed by the device in watt-hours.

Example: 231

GET/api/usage-history/date-range/realTime/average-energy/device-id/{deviceId}

curl 'http://localhost:8080/api/usage-history/date-range/realTime/average-energy/device-id/:deviceId?from=<string>&till=<string>'

Example Responses

{
  "energy": 231
}

application/json

Get hourly usage for a system within a date range with current tariff rate

GET

http://localhost:8080

/api/usage-history/date-range/system-id/hour/{systemId}

Returns hourly usage breakdown and the current tariff rate for cost calculations.

Get hourly usage for a system within a date range with current tariff rate › path Parameters

systemId

string · required

Get hourly usage for a system within a date range with current tariff rate › query Parameters

from

string · required

till

string · required

Get hourly usage for a system within a date range with current tariff rate › Responses

200

Returns hourly usage data and current tariff rate for a system.

UsageHistoryHourWithTariffResponseDto

UsageHistoryHourBreakdownDto[] · required

Array of hourly usage data

Example: [{"hour":0,"totalEnergyUsage":1.2},{"hour":1,"totalEnergyUsage":1.5}]

currentTariffRate

number | null

Current tariff rate in cost per kWh. Null if no tariff rate is configured. Useful for frontend calculations.

Example: 0.25

GET/api/usage-history/date-range/system-id/hour/{systemId}

curl 'http://localhost:8080/api/usage-history/date-range/system-id/hour/:systemId?from=<string>&till=<string>'

Example Responses

{
  "data": [
    {
      "hour": 0,
      "totalEnergyUsage": 1.2
    },
    {
      "hour": 1,
      "totalEnergyUsage": 1.5
    }
  ],
  "currentTariffRate": 0.25
}

application/json

Get hourly usage for a tenant within a date range with current tariff rate

GET

http://localhost:8080

/api/usage-history/date-range/tenant-id/hour/{tenantId}

Returns hourly usage breakdown and the current tariff rate for cost calculations.

Get hourly usage for a tenant within a date range with current tariff rate › path Parameters

tenantId

string · required

Get hourly usage for a tenant within a date range with current tariff rate › query Parameters

from

string · required

till

string · required

Get hourly usage for a tenant within a date range with current tariff rate › Responses

200

Returns hourly usage data and current tariff rate for a tenant.

UsageHistoryHourWithTariffResponseDto

UsageHistoryHourBreakdownDto[] · required

Array of hourly usage data

Example: [{"hour":0,"totalEnergyUsage":1.2},{"hour":1,"totalEnergyUsage":1.5}]

currentTariffRate

number | null

Current tariff rate in cost per kWh. Null if no tariff rate is configured. Useful for frontend calculations.

Example: 0.25

GET/api/usage-history/date-range/tenant-id/hour/{tenantId}

curl 'http://localhost:8080/api/usage-history/date-range/tenant-id/hour/:tenantId?from=<string>&till=<string>'

Example Responses

{
  "data": [
    {
      "hour": 0,
      "totalEnergyUsage": 1.2
    },
    {
      "hour": 1,
      "totalEnergyUsage": 1.5
    }
  ],
  "currentTariffRate": 0.25
}

application/json

Get hourly usage for a zone within a date range with current tariff rate

GET

http://localhost:8080

/api/usage-history/date-range/zone-id/hour/{zoneId}

Returns hourly usage breakdown and the current tariff rate for cost calculations.

Get hourly usage for a zone within a date range with current tariff rate › path Parameters

zoneId

string · required

Get hourly usage for a zone within a date range with current tariff rate › query Parameters

from

string · required

till

string · required

Get hourly usage for a zone within a date range with current tariff rate › Responses

200

Returns hourly usage data and current tariff rate for a zone.

UsageHistoryHourWithTariffResponseDto

UsageHistoryHourBreakdownDto[] · required

Array of hourly usage data

Example: [{"hour":0,"totalEnergyUsage":1.2},{"hour":1,"totalEnergyUsage":1.5}]

currentTariffRate

number | null

Current tariff rate in cost per kWh. Null if no tariff rate is configured. Useful for frontend calculations.

Example: 0.25

GET/api/usage-history/date-range/zone-id/hour/{zoneId}

curl 'http://localhost:8080/api/usage-history/date-range/zone-id/hour/:zoneId?from=<string>&till=<string>'

Example Responses

{
  "data": [
    {
      "hour": 0,
      "totalEnergyUsage": 1.2
    },
    {
      "hour": 1,
      "totalEnergyUsage": 1.5
    }
  ],
  "currentTariffRate": 0.25
}

application/json

Get hourly usage for a room within a date range with current tariff rate

GET

http://localhost:8080

/api/usage-history/date-range/room-id/hour/{roomId}

Returns hourly usage breakdown and the current tariff rate for cost calculations.

Get hourly usage for a room within a date range with current tariff rate › path Parameters

roomId

string · required

Get hourly usage for a room within a date range with current tariff rate › query Parameters

from

string · required

till

string · required

Get hourly usage for a room within a date range with current tariff rate › Responses

200

Returns hourly usage data and current tariff rate for a room.

UsageHistoryHourWithTariffResponseDto

UsageHistoryHourBreakdownDto[] · required

Array of hourly usage data

Example: [{"hour":0,"totalEnergyUsage":1.2},{"hour":1,"totalEnergyUsage":1.5}]

currentTariffRate

number | null

Current tariff rate in cost per kWh. Null if no tariff rate is configured. Useful for frontend calculations.

Example: 0.25

GET/api/usage-history/date-range/room-id/hour/{roomId}

curl 'http://localhost:8080/api/usage-history/date-range/room-id/hour/:roomId?from=<string>&till=<string>'

Example Responses

{
  "data": [
    {
      "hour": 0,
      "totalEnergyUsage": 1.2
    },
    {
      "hour": 1,
      "totalEnergyUsage": 1.5
    }
  ],
  "currentTariffRate": 0.25
}

application/json

Get hourly usage for a distribution box within a date range with current tariff rate

GET

http://localhost:8080

/api/usage-history/date-range/distribution-box-id/hour/{distributionBoxId}

Returns hourly usage breakdown and the current tariff rate for cost calculations.

Get hourly usage for a distribution box within a date range with current tariff rate › path Parameters

distributionBoxId

string · required

Get hourly usage for a distribution box within a date range with current tariff rate › query Parameters

from

string · required

till

string · required

Get hourly usage for a distribution box within a date range with current tariff rate › Responses

200

Returns hourly usage data and current tariff rate for a distribution box.

UsageHistoryHourWithTariffResponseDto

UsageHistoryHourBreakdownDto[] · required

Array of hourly usage data

Example: [{"hour":0,"totalEnergyUsage":1.2},{"hour":1,"totalEnergyUsage":1.5}]

currentTariffRate

number | null

Current tariff rate in cost per kWh. Null if no tariff rate is configured. Useful for frontend calculations.

Example: 0.25

GET/api/usage-history/date-range/distribution-box-id/hour/{distributionBoxId}

curl 'http://localhost:8080/api/usage-history/date-range/distribution-box-id/hour/:distributionBoxId?from=<string>&till=<string>'

Example Responses

{
  "data": [
    {
      "hour": 0,
      "totalEnergyUsage": 1.2
    },
    {
      "hour": 1,
      "totalEnergyUsage": 1.5
    }
  ],
  "currentTariffRate": 0.25
}

application/json

Get Usage and Energy Cost for a system from beginning to date

GET

http://localhost:8080

/api/usage-history/to-date/system-id/{systemId}

Returns total energy usage and calculated cost based on current tariff rate. Cost will be null if no tariff rate is configured for the system.

Get Usage and Energy Cost for a system from beginning to date › path Parameters

systemId

string · required

Get Usage and Energy Cost for a system from beginning to date › Responses

200

Returns usage, cost, and tariff rate for a system. Cost is calculated as totalEnergyUsage * tariffRate.

UsageWithCostResponseDto

totalEnergyUsage

number · required

Total energy usage in kWh

Example: 125.5

totalCost

number | null

Total cost based on current tariff rate. Null if no tariff rate is configured.

Example: 31.375

tariffRate

number | null

Current tariff rate in cost per kWh. Null if no tariff rate is configured.

Example: 0.25

GET/api/usage-history/to-date/system-id/{systemId}

curl http://localhost:8080/api/usage-history/to-date/system-id/:systemId

Example Responses

{
  "totalEnergyUsage": 125.5,
  "totalCost": 31.375,
  "tariffRate": 0.25
}

application/json

Get Usage and Energy Cost for a tenant from beginning to date

GET

http://localhost:8080

/api/usage-history/to-date/tenant-id/{tenantId}

Returns total energy usage and calculated cost based on current tariff rate. Cost will be null if no tariff rate is configured for the system.

Get Usage and Energy Cost for a tenant from beginning to date › path Parameters

tenantId

string · required

Get Usage and Energy Cost for a tenant from beginning to date › Responses

200

Returns usage, cost, and tariff rate for a tenant. Cost is calculated as totalEnergyUsage * tariffRate.

UsageWithCostResponseDto

totalEnergyUsage

number · required

Total energy usage in kWh

Example: 125.5

totalCost

number | null

Total cost based on current tariff rate. Null if no tariff rate is configured.

Example: 31.375

tariffRate

number | null

Current tariff rate in cost per kWh. Null if no tariff rate is configured.

Example: 0.25

GET/api/usage-history/to-date/tenant-id/{tenantId}

curl http://localhost:8080/api/usage-history/to-date/tenant-id/:tenantId

Example Responses

{
  "totalEnergyUsage": 125.5,
  "totalCost": 31.375,
  "tariffRate": 0.25
}

application/json

Get Usage and Energy Cost for a zone from beginning to date

GET

http://localhost:8080

/api/usage-history/to-date/zone-id/{zoneId}

Returns total energy usage and calculated cost based on current tariff rate. Cost will be null if no tariff rate is configured for the system.

Get Usage and Energy Cost for a zone from beginning to date › path Parameters

zoneId

string · required

Get Usage and Energy Cost for a zone from beginning to date › Responses

200

Returns usage, cost, and tariff rate for a zone. Cost is calculated as totalEnergyUsage * tariffRate.

UsageWithCostResponseDto

totalEnergyUsage

number · required

Total energy usage in kWh

Example: 125.5

totalCost

number | null

Total cost based on current tariff rate. Null if no tariff rate is configured.

Example: 31.375

tariffRate

number | null

Current tariff rate in cost per kWh. Null if no tariff rate is configured.

Example: 0.25

GET/api/usage-history/to-date/zone-id/{zoneId}

curl http://localhost:8080/api/usage-history/to-date/zone-id/:zoneId

Example Responses

{
  "totalEnergyUsage": 125.5,
  "totalCost": 31.375,
  "tariffRate": 0.25
}

application/json

Get Usage and Energy Cost for a room from beginning to date

GET

http://localhost:8080

/api/usage-history/to-date/room-id/{roomId}

Returns total energy usage and calculated cost based on current tariff rate. Cost will be null if no tariff rate is configured for the system.

Get Usage and Energy Cost for a room from beginning to date › path Parameters

roomId

string · required

Get Usage and Energy Cost for a room from beginning to date › Responses

200

Returns usage, cost, and tariff rate for a room. Cost is calculated as totalEnergyUsage * tariffRate.

UsageWithCostResponseDto

totalEnergyUsage

number · required

Total energy usage in kWh

Example: 125.5

totalCost

number | null

Total cost based on current tariff rate. Null if no tariff rate is configured.

Example: 31.375

tariffRate

number | null

Current tariff rate in cost per kWh. Null if no tariff rate is configured.

Example: 0.25

GET/api/usage-history/to-date/room-id/{roomId}

curl http://localhost:8080/api/usage-history/to-date/room-id/:roomId

Example Responses

{
  "totalEnergyUsage": 125.5,
  "totalCost": 31.375,
  "tariffRate": 0.25
}

application/json

Get Usage and Energy Cost for a device (Plug/MCB/Distribution Box) from beginning to date

GET

http://localhost:8080

/api/usage-history/to-date/device-id/{deviceId}

Returns total energy usage and calculated cost based on current tariff rate for any device type. Cost will be null if no tariff rate is configured for the system. This endpoint works for Plugs, MCBs, and Distribution Boxes.

Get Usage and Energy Cost for a device (Plug/MCB/Distribution Box) from beginning to date › path Parameters

deviceId

string · required

Get Usage and Energy Cost for a device (Plug/MCB/Distribution Box) from beginning to date › Responses

200

Returns usage, cost, and tariff rate for a device. Cost is calculated as totalEnergyUsage * tariffRate.

UsageWithCostResponseDto

totalEnergyUsage

number · required

Total energy usage in kWh

Example: 125.5

totalCost

number | null

Total cost based on current tariff rate. Null if no tariff rate is configured.

Example: 31.375

tariffRate

number | null

Current tariff rate in cost per kWh. Null if no tariff rate is configured.

Example: 0.25

GET/api/usage-history/to-date/device-id/{deviceId}

curl http://localhost:8080/api/usage-history/to-date/device-id/:deviceId

Example Responses

{
  "totalEnergyUsage": 125.5,
  "totalCost": 31.375,
  "tariffRate": 0.25
}

application/json

Get hourly records for a Smart Switch device within a date range

GET

http://localhost:8080

/api/usage-history/smart-switch/hourly/{deviceId}

Returns hourly downtime records for SMART_SWITCH devices, including gang switch states reported by the device.

Get hourly records for a Smart Switch device within a date range › path Parameters

deviceId

string · required

Get hourly records for a Smart Switch device within a date range › query Parameters

from

string · required

till

string · required

Get hourly records for a Smart Switch device within a date range › Responses

200

Hourly Smart Switch records (downTime, onStatus, gangSwitchStatus)

UsageHistoryHourSmartSwitchResponseDto[]

UsageHistoryHourSmartSwitchResponseDto

hour

number · required

Hour of the day (0–23)

Example: 7

onStatus

string · enum · required

Device on/off status for this hour

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

createdAt

string · date-time · required

Record creation timestamp

Example: 2024-01-15T07:10:00.000Z

downTime

number

Total downtime in milliseconds for this hour (3600000 = full hour down)

Example: 1800000

gangSwitchStatus

number[]

Gang switch states reported by the device (array index = gang index, 1 = ON, 0 = OFF)

Example: [1,0,1]

actualDate

string · date-time

Actual date this hourly record is for

Example: 2024-01-15T07:00:00.000Z

GET/api/usage-history/smart-switch/hourly/{deviceId}

curl 'http://localhost:8080/api/usage-history/smart-switch/hourly/:deviceId?from=<string>&till=<string>'

Example Responses

[
  {
    "hour": 7,
    "onStatus": "ON",
    "downTime": 1800000,
    "gangSwitchStatus": [
      1,
      0,
      1
    ],
    "actualDate": "2024-01-15T07:00:00.000Z",
    "createdAt": "2024-01-15T07:10:00.000Z"
  }
]

application/json

Get real-time readings for an Aircon Control device within a date range

GET

http://localhost:8080

/api/usage-history/aircon-control/realtime/{deviceId}

Returns real-time ambient temperature and humidity readings (limited to 1000 records) for AIRCON_CONTROL devices that support sensor readings.

Get real-time readings for an Aircon Control device within a date range › path Parameters

deviceId

string · required

Get real-time readings for an Aircon Control device within a date range › query Parameters

from

string · required

till

string · required

Get real-time readings for an Aircon Control device within a date range › Responses

200

Real-time aircon control readings (ambientTemperature, ambientHumidity)

UsageHistoryAirconControlRealtimeResponseDto[]

UsageHistoryAirconControlRealtimeResponseDto

onStatus

string · enum · required

Device on/off status

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

createdAt

string · date-time · required

Record creation timestamp

ambientTemperature

number

Ambient temperature in Celsius

Example: 24.5

ambientHumidity

number

Ambient humidity percentage

Example: 65

GET/api/usage-history/aircon-control/realtime/{deviceId}

curl 'http://localhost:8080/api/usage-history/aircon-control/realtime/:deviceId?from=<string>&till=<string>'

Example Responses

[
  {
    "onStatus": "ON",
    "ambientTemperature": 24.5,
    "ambientHumidity": 65,
    "createdAt": "2024-08-25T15:00:00Z"
  }
]

application/json

Get hourly records for an Aircon Control device within a date range

GET

http://localhost:8080

/api/usage-history/aircon-control/hourly/{deviceId}

Returns hourly downtime records for AIRCON_CONTROL devices.

Get hourly records for an Aircon Control device within a date range › path Parameters

deviceId

string · required

Get hourly records for an Aircon Control device within a date range › query Parameters

from

string · required

till

string · required

Get hourly records for an Aircon Control device within a date range › Responses

200

Hourly Aircon Control records (downTime, onStatus)

UsageHistoryHourAirconControlResponseDto[]

UsageHistoryHourAirconControlResponseDto

hour

number · required

Hour of the day (0–23)

Example: 7

onStatus

string · enum · required

Device on/off status for this hour

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

createdAt

string · date-time · required

Record creation timestamp

Example: 2024-01-15T07:10:00.000Z

downTime

number

Total downtime in milliseconds for this hour (3600000 = full hour down)

Example: 1800000

ambientTemperature

number

Ambient temperature in Celsius

Example: 24.5

ambientHumidity

number

Ambient humidity percentage

Example: 65

actualDate

string · date-time

Actual date this hourly record is for

Example: 2024-01-15T07:00:00.000Z

GET/api/usage-history/aircon-control/hourly/{deviceId}

curl 'http://localhost:8080/api/usage-history/aircon-control/hourly/:deviceId?from=<string>&till=<string>'

Example Responses

[
  {
    "hour": 7,
    "onStatus": "ON",
    "downTime": 1800000,
    "ambientTemperature": 24.5,
    "ambientHumidity": 65,
    "actualDate": "2024-01-15T07:00:00.000Z",
    "createdAt": "2024-01-15T07:10:00.000Z"
  }
]

application/json

Get hourly box plot aggregation for environment sensors on a given date

GET

http://localhost:8080

/api/usage-history/environment-sensor/hourly-boxplot

Aggregates real-time readings across multiple sensors, grouped by hour. Returns box plot statistics (min, Q1, median, Q3, max) using linear interpolation, plus available metrics based on sensor types.

Get hourly box plot aggregation for environment sensors on a given date › query Parameters

sensorIds

string · required

Comma-separated environment sensor device IDs

Example: 60f7c2b3e1b3c2a1d4e5f6a7,60f7c2b3e1b3c2a1d4e5f6a8

date

string · required

Date in YYYY-MM-DD format

Example: 2026-03-20

metric

string · enum · required

Metric field to aggregate

Enum values:

temperature

humidity

carbonDioxide

formaldehyde

fineParticulateMatter

coarseParticulateMatter

totalVolatileOrganicCompounds

soundLevel

Example: temperature

Get hourly box plot aggregation for environment sensors on a given date › Responses

200

Hourly box plot entries with available metrics for the requested sensors

HourlyBoxplotResponseDto

HourlyBoxplotEntryDto[] · required

Hourly box plot entries (only hours with data)

availableMetrics

string[] · required

Available metrics based on the sensor types of the requested sensors

Example: ["temperature","humidity","carbonDioxide","formaldehyde"]

GET/api/usage-history/environment-sensor/hourly-boxplot

curl 'http://localhost:8080/api/usage-history/environment-sensor/hourly-boxplot?sensorIds=<string>&date=<string>&metric=<string>'

Example Responses

{
  "data": [
    {
      "min": 22.1,
      "q1": 23.5,
      "median": 24.8,
      "q3": 26.2,
      "max": 28,
      "hour": 14,
      "sensorCount": 5
    }
  ],
  "availableMetrics": [
    "temperature",
    "humidity",
    "carbonDioxide",
    "formaldehyde"
  ]
}

application/json

Get drilldown data for a specific hour with per-sensor breakdown

GET

http://localhost:8080

/api/usage-history/environment-sensor/hourly-drilldown

Returns overall box plot statistics and per-sensor mean values for a specific date and hour. Useful for inspecting which sensors contributed to a particular hourly box plot.

Get drilldown data for a specific hour with per-sensor breakdown › query Parameters

sensorIds

string · required

Comma-separated environment sensor device IDs

Example: 60f7c2b3e1b3c2a1d4e5f6a7,60f7c2b3e1b3c2a1d4e5f6a8

date

string · required

Date in YYYY-MM-DD format

Example: 2026-03-20

hour

number · required

Hour of the day (0-23)

Example: 14

metric

string · enum · required

Metric field to aggregate

Enum values:

temperature

humidity

carbonDioxide

formaldehyde

fineParticulateMatter

coarseParticulateMatter

totalVolatileOrganicCompounds

soundLevel

Example: temperature

Get drilldown data for a specific hour with per-sensor breakdown › Responses

200

Overall box stats, per-sensor breakdown, total readings and sensor count

HourlyDrilldownResponseDto

object · required

Overall box plot statistics across all readings

SensorBreakdownDto[] · required

Per-sensor breakdown with mean values

totalSensors

number · required

Total number of sensors with data

Example: 5

GET/api/usage-history/environment-sensor/hourly-drilldown

curl 'http://localhost:8080/api/usage-history/environment-sensor/hourly-drilldown?sensorIds=<string>&date=<string>&hour=<number>&metric=<string>'

Example Responses

{
  "overallBoxStats": {
    "min": 22.1,
    "q1": 23.5,
    "median": 24.8,
    "q3": 26.2,
    "max": 28
  },
  "sensorBreakdown": [
    {
      "sensorId": "sensorId",
      "sensorName": "Office IAQ Sensor",
      "mean": 24.5
    }
  ],
  "totalSensors": 5
}

application/json

Get hourly environment readings for a sensor within a date range - New Architecture

GET

http://localhost:8080

/api/usage-history/environment-sensor/hourly/{deviceId}

Uses EnvironmentSensorUsageHistoryService. Returns hourly readings for all environmental metrics for ENV_SENSOR devices.

Get hourly environment readings for a sensor within a date range - New Architecture › path Parameters

deviceId

string · required

Get hourly environment readings for a sensor within a date range - New Architecture › query Parameters

from

string · required

till

string · required

Get hourly environment readings for a sensor within a date range - New Architecture › Responses

200

Hourly environment readings (temperature, humidity, CO2, PM2.5, TVOC, sound, motion, etc.)

UsageHistoryHourEnvironmentSensor[]

UsageHistoryHourEnvironmentSensor

_id

string · required

Primary ID of the UsageHistoryHour

Example: 64b7f1e6f9c9d4e5b8a9f7c3

hour

number · required

No. What Hour (E.g. 7 means 0700 - 0800)

Example: 7

onStatus

string · enum · required

Status of the Plug (ON / OFF)

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

deviceType

string · enum · required

Type of device (PLUG, MCB, etc.)

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

Example: PLUG

createdAt

string · date-time · required

Date Time of the Creation

Example: 2021-09-01

updatedAt

string · date-time · required

Date Time of the Update

Example: 2021-09-01

actualDate

string · date-time · required

Date Time of the Update

Example: 2021-09-01

macId

string · required

MAC ID of the device

Example: 1092384701928347

device

string · required

Reference to the device

Example: 64b7f1e6f9c9d4e5b8a9f7c3

carbonDioxide

number · required

Current CO2 reading in ppm

Example: 400

formaldehyde

number · required

Current formaldehyde (HCHO) reading in ppm

Example: 0.03

temperature

number · required

Current temperature reading in degrees Celsius

Example: 24

humidity

number · required

Current humidity percentage

Example: 24

fineParticulateMatter

number · required

Current Fine Particulate Matter in µg/m3

Example: 1

coarseParticulateMatter

number · required

Current Coarse Particulate Matter in µg/m3

Example: 1

totalVolatileOrganicCompounds

number · required

Total Volatile Organic Compounds in ppm

Example: 1

soundLevel

number · required

Current Sound Level in dB

Example: 1

motionDetected

boolean · required

Motion detection status

Example: true

wifiStrength

number

WiFi signal strength at the time of the hourly record

Example: -65

GET/api/usage-history/environment-sensor/hourly/{deviceId}

curl 'http://localhost:8080/api/usage-history/environment-sensor/hourly/:deviceId?from=<string>&till=<string>'

Example Responses

[
  {
    "_id": "64b7f1e6f9c9d4e5b8a9f7c3",
    "hour": "7",
    "onStatus": "ON",
    "deviceType": "PLUG",
    "createdAt": "2021-09-01",
    "updatedAt": "2021-09-01",
    "actualDate": "2021-09-01",
    "macId": "1092384701928347",
    "wifiStrength": -65,
    "device": "64b7f1e6f9c9d4e5b8a9f7c3",
    "carbonDioxide": 400,
    "formaldehyde": 0.03,
    "temperature": 24,
    "humidity": 24,
    "fineParticulateMatter": 1,
    "coarseParticulateMatter": 1,
    "totalVolatileOrganicCompounds": 1,
    "soundLevel": 1,
    "motionDetected": true
  }
]

application/json

Get real-time environment readings for a sensor within a date range - New Architecture

GET

http://localhost:8080

/api/usage-history/environment-sensor/realtime/{deviceId}

Uses EnvironmentSensorUsageHistoryService. Returns real-time readings (limited to 1000 records) for ENV_SENSOR devices.

Get real-time environment readings for a sensor within a date range - New Architecture › path Parameters

deviceId

string · required

Get real-time environment readings for a sensor within a date range - New Architecture › query Parameters

from

string · required

till

string · required

Get real-time environment readings for a sensor within a date range - New Architecture › Responses

200

Real-time environment readings (limited to 1000 most recent records within date range)

UsageHistoryEnvironmentSensor[]

UsageHistoryEnvironmentSensor

_id

string · required

Primary ID of the Usage History Real Time

Example: 64b7f1e6f9c9d4e5b8a9f7c3

onStatus

string · enum · required

Status of the device (ON / OFF)

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

deviceType

string · enum · required

Type of device (PLUG, MCB, etc.)

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

Example: PLUG

macId

string · required

MAC ID of the device

Example: 1092384701928347

device

string · required

Reference to the device

Example: 64b7f1e6f9c9d4e5b8a9f7c3

createdAt

string · date-time · required

Date Time of the Creation

Example: 2021-09-01

temperature

number · required

Current temperature reading in degrees Celsius

Example: 24

carbonDioxide

number · required

Current CO2 reading in ppm

Example: 400

formaldehyde

number · required

Current formaldehyde (HCHO) reading in ppm

Example: 0.03

humidity

number · required

Current humidity percentage

Example: 24

fineParticulateMatter

number · required

Current Fine Particulate Matter in µg/m3

Example: 1

coarseParticulateMatter

number · required

Current Coarse Particulate Matter in µg/m3

Example: 1

totalVolatileOrganicCompounds

number · required

Total Volatile Organic Compounds in ppm

Example: 1

soundLevel

number · required

Current Sound Level in dB

Example: 1

motionDetected

boolean · required

Motion detection status

Example: true

GET/api/usage-history/environment-sensor/realtime/{deviceId}

curl 'http://localhost:8080/api/usage-history/environment-sensor/realtime/:deviceId?from=<string>&till=<string>'

Example Responses

[
  {
    "_id": "64b7f1e6f9c9d4e5b8a9f7c3",
    "onStatus": "ON",
    "deviceType": "PLUG",
    "macId": "1092384701928347",
    "device": "64b7f1e6f9c9d4e5b8a9f7c3",
    "createdAt": "2021-09-01",
    "temperature": 24,
    "carbonDioxide": 400,
    "formaldehyde": 0.03,
    "humidity": 24,
    "fineParticulateMatter": 1,
    "coarseParticulateMatter": 1,
    "totalVolatileOrganicCompounds": 1,
    "soundLevel": 1,
    "motionDetected": true
  }
]

application/json

Get hourly water meter readings for a device within a date range

GET

http://localhost:8080

/api/usage-history/water-meter/hourly/{deviceId}

Returns hourly water consumption readings including flow rate, pressure, and temperature for WATER_METER devices.

Get hourly water meter readings for a device within a date range › path Parameters

deviceId

string · required

Get hourly water meter readings for a device within a date range › query Parameters

from

string · required

till

string · required

Get hourly water meter readings for a device within a date range › Responses

200

Hourly water meter readings (flow rate, pressure, temperature, consumption)

UsageHistoryHourWaterMeter[]

UsageHistoryHourWaterMeter

_id

string · required

Primary ID of the UsageHistoryHour

Example: 64b7f1e6f9c9d4e5b8a9f7c3

hour

number · required

No. What Hour (E.g. 7 means 0700 - 0800)

Example: 7

onStatus

string · enum · required

Device status during this hour

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

deviceType

string · enum · required

Type of device (PLUG, MCB, etc.)

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

Example: PLUG

createdAt

string · date-time · required

Date Time of the Creation

Example: 2021-09-01

updatedAt

string · date-time · required

Date Time of the Update

Example: 2021-09-01

actualDate

string · date-time · required

Date Time of the Update

Example: 2021-09-01

macId

string · required

MAC ID of the device

Example: 1092384701928347

device

string · required

Reference to the device

Example: 64b7f1e6f9c9d4e5b8a9f7c3

waterConsumption

number · required

Total water consumption for this hour (liters)

realTimeFlowRate

number · required

Average flow rate for this hour (L/min)

realTimePressure

number · required

Average pressure for this hour (bar)

wifiStrength

number

WiFi signal strength at the time of the hourly record

Example: -65

realTimeTemperature

number

Average temperature for this hour (Celsius)

GET/api/usage-history/water-meter/hourly/{deviceId}

curl 'http://localhost:8080/api/usage-history/water-meter/hourly/:deviceId?from=<string>&till=<string>'

Example Responses

[
  {
    "_id": "64b7f1e6f9c9d4e5b8a9f7c3",
    "hour": "7",
    "onStatus": "ON",
    "deviceType": "PLUG",
    "createdAt": "2021-09-01",
    "updatedAt": "2021-09-01",
    "actualDate": "2021-09-01",
    "macId": "1092384701928347",
    "wifiStrength": -65,
    "device": "64b7f1e6f9c9d4e5b8a9f7c3",
    "waterConsumption": 0,
    "realTimeFlowRate": 0,
    "realTimePressure": 0,
    "realTimeTemperature": 0
  }
]

application/json

Get real-time water meter readings for a device within a date range

GET

http://localhost:8080

/api/usage-history/water-meter/realtime/{deviceId}

Returns real-time water consumption readings (limited to 1000 records) for WATER_METER devices.

Get real-time water meter readings for a device within a date range › path Parameters

deviceId

string · required

Get real-time water meter readings for a device within a date range › query Parameters

from

string · required

till

string · required

Get real-time water meter readings for a device within a date range › Responses

200

Real-time water meter readings (limited to 1000 most recent records within date range)

UsageHistoryWaterMeter[]

UsageHistoryWaterMeter

_id

string · required

Primary ID of the Usage History Real Time

Example: 64b7f1e6f9c9d4e5b8a9f7c3

onStatus

string · enum · required

Device status

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

deviceType

string · enum · required

Type of device (PLUG, MCB, etc.)

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

Example: PLUG

macId

string · required

MAC ID of the device

Example: 1092384701928347

device

string · required

Reference to the device

Example: 64b7f1e6f9c9d4e5b8a9f7c3

createdAt

string · date-time · required

Date Time of the Creation

Example: 2021-09-01

realTimeFlowRate

number · required

Current flow rate in liters per minute (L/min)

realTimePressure

number · required

Water pressure in bar

waterConsumption

number · required

Cumulative water consumption in liters

realTimeTemperature

number

Water temperature in Celsius

GET/api/usage-history/water-meter/realtime/{deviceId}

curl 'http://localhost:8080/api/usage-history/water-meter/realtime/:deviceId?from=<string>&till=<string>'

Example Responses

[
  {
    "_id": "64b7f1e6f9c9d4e5b8a9f7c3",
    "onStatus": "ON",
    "deviceType": "PLUG",
    "macId": "1092384701928347",
    "device": "64b7f1e6f9c9d4e5b8a9f7c3",
    "createdAt": "2021-09-01",
    "realTimeFlowRate": 0,
    "realTimePressure": 0,
    "realTimeTemperature": 0,
    "waterConsumption": 0
  }
]

application/json

Get daily water meter readings for a device within a date range

GET

http://localhost:8080

/api/usage-history/water-meter/daily/{deviceId}

Returns daily water consumption aggregates including total consumption, average flow rate, pressure, and temperature for WATER_METER devices.

Get daily water meter readings for a device within a date range › path Parameters

deviceId

string · required

Get daily water meter readings for a device within a date range › query Parameters

from

string · required

till

string · required

Get daily water meter readings for a device within a date range › Responses

200

Daily water meter readings (total consumption, avg flow rate, avg pressure, avg temperature)

UsageHistoryDayWaterMeter[]

UsageHistoryDayWaterMeter

_id

string · required

Primary ID of the UsageHistoryDay

Example: 64b7f1e6f9c9d4e5b8a9f7c3

UsageHistoryHour[] · required

Usage History of the device (Hourly)

createdAt

string · date-time · required

Date Time of the Creation

Example: 2021-09-01

updatedAt

string · date-time · required

Date Time of the Update

Example: 2021-09-01

deviceType

string · enum · required

Type of device (PLUG, MCB, etc.)

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

Example: PLUG

macId

string · required

MAC ID of the device

Example: 1092384701928347

device

string · required

Reference to the device

Example: 64b7f1e6f9c9d4e5b8a9f7c3

waterConsumption

number · required

Total daily water consumption (liters)

realTimeFlowRate

number · required

Average daily flow rate (L/min)

realTimePressure

number · required

Average daily pressure (bar)

realTimeTemperature

number

Average daily temperature (Celsius)

GET/api/usage-history/water-meter/daily/{deviceId}

curl 'http://localhost:8080/api/usage-history/water-meter/daily/:deviceId?from=<string>&till=<string>'

Example Responses

[
  {
    "_id": "64b7f1e6f9c9d4e5b8a9f7c3",
    "usageHistoryHourly": [
      {
        "_id": "64b7f1e6f9c9d4e5b8a9f7c3",
        "hour": "7",
        "onStatus": "ON",
        "deviceType": "PLUG",
        "createdAt": "2021-09-01",
        "updatedAt": "2021-09-01",
        "actualDate": "2021-09-01",
        "macId": "1092384701928347",
        "wifiStrength": -65,
        "device": "64b7f1e6f9c9d4e5b8a9f7c3"
      }
    ],
    "createdAt": "2021-09-01",
    "updatedAt": "2021-09-01",
    "deviceType": "PLUG",
    "macId": "1092384701928347",
    "device": "64b7f1e6f9c9d4e5b8a9f7c3",
    "waterConsumption": 0,
    "realTimeFlowRate": 0,
    "realTimePressure": 0,
    "realTimeTemperature": 0
  }
]

application/json

Usage History - Device-Level Retrieval & Analytics