Peer Comparison

The comparison endpoint enriches daily energy statistics with percentile rankings against a group of comparable buildings. This powers "How do I compare?" features in your Households Dashboard.

A building’s energy data with daily readings, and comparison with comparable buildings

get

Get energy related data of a building, aggregated on a daily basis and compare it with comparable buildings. The comparison group has the following values:

• Rank in comparison group. Rank 1 is the one with highest value.

• Size of the comparison group.

• Minimum value in the comparison group.

• Maximum value in the comparison group.

• 25th percentile in the comparison group.

• Median (50th percentile) in the comparison group.

• 75th percentile in the comparison group.

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

customerBuildingIdstringRequiredPattern: ^[a-zA-Z0-9:._-]{1,100}$

Query parameters

fromstringRequired

The starting date of the time window for selecting event data.
Remark: The building's local time zone is taken into account.

Example: 2024-01-01Pattern: [0-9]{4}-[0-9]{2}-[0-9]{2}

tostringRequired

The final date of the time window for selecting event data.
Remark: the time window can be up to 1 year.

Example: 2024-01-31Pattern: [0-9]{4}-[0-9]{2}-[0-9]{2}

categorystring · enumRequired

The profile comparison category that is to be used for the comparison.

Example: ELCOMPossible values:

Responses

200

OK

application/json

daystringOptional

get

/buildings/{customerBuildingId}/energy-statistics/comparison/daily/v1

HTTPcURLJavaScriptPython

GET /buildings/{customerBuildingId}/energy-statistics/comparison/daily/v1?eventTypes=ENERGY_GENERATION_YESTERDAY&from=text&to=text&category=GRID_POWER_CONSUMPTION_CLUSTER HTTP/1.1
Host: api.moost.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

OK

[
  {
    "day": "text",
    "energyGeneration": {
      "value": 1,
      "rank": 1,
      "size": 1,
      "min": 1,
      "max": 1,
      "p25": 1,
      "median": 1,
      "p75": 1
    },
    "energyConsumption": {
      "value": 1,
      "rank": 1,
      "size": 1,
      "min": 1,
      "max": 1,
      "p25": 1,
      "median": 1,
      "p75": 1
    },
    "gridEnergyConsumption": {
      "value": 1,
      "rank": 1,
      "size": 1,
      "min": 1,
      "max": 1,
      "p25": 1,
      "median": 1,
      "p75": 1
    }
  }
]

Dashboard Usage

The peer comparison data is typically rendered in the Households Dashboard as a ranking indicator with a comparison trend chart. The MOOST admin frontend shows this in the Household Detail → Dashboard tab as a card displaying, for example, "Rank 2 of 2" with the category label (e.g. VERY_HIGH).

Percentile bars or box-plot-style visualisations work well for showing the building's position relative to p25, median, and p75.