# Households Dashboard
The energy-statistics and forecast endpoints are designed to power a **Households Dashboard** in your end-user application. The MOOST admin frontend provides a reference implementation of such a dashboard (visible in the Household Detail → Dashboard tab), which you can use as inspiration for your own.
## Dashboard Components
### Data Point Summary Cards
The top row of cards shows the total number of data points available for the selected date range. These counters give a quick indication of data completeness and coverage.
| Card | Description |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **Grid energy consumption** | Number of data points for energy drawn from the grid. |
| **Energy consumption** | Number of data points for total energy consumed by the household. |
| **Energy generation** | Number of data points for energy generated (e.g. solar). Displayed in green to distinguish generation from consumption. |
### Yearly Overview Cards
The second row provides a 12-month rolling view of the household's energy profile. Each card includes a headline value and a trend chart.
| Card | Description |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| **Grid energy consumption over a year** | Total grid energy consumed within the last 12 months (in kWh), with a monthly trend chart. |
| **Energy consumption over a year** | Total energy consumed within the last 12 months (in kWh), with a monthly trend chart. |
| **Energy generation over a year** | Total energy generated within the last 12 months (in kWh), with a monthly trend chart displayed in green. |
### Seasonal and Peak Cards
The remaining rows surface patterns and extremes that can drive personalised energy recommendations.
#### **Seasonal Patterns**
| Card | Description |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Energy consumption in winter** | Percentage of the household's energy consumption that occurs during winter months, with a monthly bar chart showing the seasonal distribution. |
| **Energy consumption at night** | Proportion of total energy consumption accounted for by nighttime hours, with a daily bar chart. A value of 100% indicates all recorded consumption occurred at night. |
#### **Daily Peaks**
| Card | Description |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| **Highest daily grid consumption** | The peak single-day grid energy consumption in the last month (in kWh), with a daily bar chart for the full month. |
| **Highest daily consumption** | The peak single-day total energy consumption in the last month (in kWh), with a daily bar chart. |
| **Highest daily generation** | The peak single-day energy generation in the last month (in kWh), with a daily bar chart displayed in yellow/green. |
#### **Hourly Peaks**
| Card | Description |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Highest hourly grid consumption** | The hour of day with the highest grid energy consumption in the last month (e.g. "23 to 24 o'clock"), with a histogram showing energy consumption by hour of day. |
| **Highest hourly consumption** | The hour of day with the highest total energy consumption in the last month, with a histogram by hour of day. |
| **Highest hourly generation** | The hour of day with the highest energy generation in the last month (e.g. "0 to 1 o'clock"), with a histogram by hour of day. |
### Peer Comparison
| Card | Description |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Energy consumption comparison** | Ranks the household's energy consumption against other households in the same consumer category. Displays a rank (e.g. "Rank 2 of 2") and the category label (e.g. `VERY_HIGH`), along with a comparison trend chart. |
## Mapping Dashboard Widgets to API Endpoints
| Dashboard Widget | API Endpoint | Event Types | Resolution |
| ------------------------ | -------------------------------------------------------------- | -------------------------------------------------------------------- | -------------- |
| Today's energy chart | `/energy-statistics/hourly/v1` | `ENERGY_CONSUMPTION`, `ENERGY_GENERATION`, `GRID_ENERGY_CONSUMPTION` | Hourly |
| This month's daily chart | `/energy-statistics/daily/v1` | `*_YESTERDAY` variants | Daily |
| Yearly overview cards | `/energy-statistics/monthly/v1` | `*_YESTERDAY` variants | Monthly |
| Seasonal / peak cards | `/energy-statistics/daily/v1` + `/energy-statistics/hourly/v1` | Various | Daily + Hourly |
| Peer comparison | `/energy-statistics/comparison/daily/v1` | `*_YESTERDAY` variants + `category` | Daily |
| Generation forecast | `/energy-forecast/v1` | `ENERGY_GENERATION_FORECAST_*` | Per forecast |
| Consumption forecast | `/energy-forecast/v1` | `ENERGY_CONSUMPTION_FORECAST_*` | Per forecast |
| Base load monitoring | `/energy-statistics/daily/v1` | `ENERGY_BASE_CONSUMPTION`, `GRID_ENERGY_BASE_CONSUMPTION` | Daily |
## Chart Guidelines
Values on the y-axis are in kWh and on the x-axis in the relevant time unit (month, day, or hour):
* **Line charts** are used for yearly trend cards, showing monthly aggregated values.
* **Bar charts** are used for daily and seasonal cards, showing per-day values.
* **Histograms** are used for hourly peak cards, showing energy distribution across hours of the day.
Hover over data points in the platform to see exact values.
## Building Your Own Dashboard
When implementing your own Households Dashboard, we recommend starting with the following minimum set of widgets:
1. **Yearly overview** (monthly endpoint) — gives the user a high-level sense of their energy profile.
2. **Daily detail** (daily endpoint) — lets the user drill into a specific month.
3. **Intraday chart** (hourly endpoint) — shows today's energy flow in real time.
4. **Peer comparison** (comparison endpoint) — provides social context and motivation.
5. **Forecast** (forecast endpoint) — enables forward-looking planning.
Use the MOOST admin frontend (Household Detail → Dashboard tab) as a reference for layout, colour coding (green for generation, default for consumption), and card design.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://doc.moost.io/technical-integration/cloud-to-cloud-integration/intelligence-service-integration/households-dashboard.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.