Skip to main content

Energy Metrics & Forecasts

This section explains how to read consumption, production, energy history, forecasts and PV plant health using Homsai APIs.

Overview​

Energy metrics endpoints allow you to:

  • read aggregated consumption and production (daily, hourly);
  • obtain consumption and production forecasts;
  • access detailed sensor history;
  • evaluate the photovoltaic plant “health” (performance vs. expected).

In this guide you will see:

Energy consumption​

Power consumption endpoints return information about a plant’s electrical consumption.

  • Daily consumption (last 7 days)

    • Endpoint: GET /plants/{plantUuid}/daily-power-consumptions
    • Parameters:
      • date (optional, yyyy-MM-dd): reference day; if omitted, a default (e.g. today) is used to compute the last 7 days window.
    • Typical use: daily bar charts for the last days.

  • Hourly consumption (last 24 hours)

    • Endpoint: GET /plants/{plantUuid}/hourly-power-consumptions
    • Parameters:
      • date (optional): reference day for the last 24 hours window.
    • Typical use: hourly consumption trend for a given day.

  • Daily consumption summary (custom range)

    • Endpoint: GET /plants/{plantUuid}/summary-daily-power-consumptions
    • Parameters:
      • startDate (required, yyyy-MM-dd): range start;
      • endDate (optional, yyyy-MM-dd): range end; if omitted, a default or the latest available is used.
    • Typical use: weekly/monthly reports with per‑day aggregation.

  • Plant consumption forecast

    • Endpoint: GET /plants/{plantUuid}/predict-power-consumption
    • Purpose: get a forecast of the plant’s future consumption, based on historical data and internal models.

All these endpoints require:

  • a valid accessToken;
  • permission PLANT_POWER_CONSUMPTION READ;
  • ownership on the plant.

Energy production​

Power production endpoints return information about energy production, typically from PV.

  • Daily production (last 7 days)

    • Endpoint: GET /plants/{plantUuid}/daily-power-productions
    • Parameters:
      • date (optional, yyyy-MM-dd): reference day.
    • Typical use: daily production bar charts.

  • Hourly production (last 24 hours)

    • Endpoint: GET /plants/{plantUuid}/hourly-power-productions
    • Parameters:
      • date (optional): reference day.
    • Typical use: hourly PV production curve for a given day.

  • Plant production forecast

    • Endpoint: GET /plants/{plantUuid}/predict-power-production
    • Purpose: get a forecast of future production (for example to optimize self‑consumption and battery usage).

These endpoints require:

  • a valid accessToken;
  • permission PLANT_POWER_PRODUCTION READ;
  • plant ownership.

Daily forecasts​

Beyond aggregated consumption/production forecasts, Homsai exposes detailed daily forecasts per device type.

  • Daily forecasts by device type
    • Endpoint: GET /plants/{plantUuid}/predict
    • Parameters:
      • consumerOnly (optional, boolean): if true, limits forecasts to consumer devices only.
    • Result: typically a structure mapping device types to forecast time series (for each device type, a list of timestamps with predicted values).

Typical use cases:

  • building separate forecast charts for production, specific loads, EV charging, etc.;
  • planning automation scenarios (e.g. shifting loads to hours with higher PV production).

Requires permission DAILY_PREDICTIONS READ and plant ownership.

Sensor history​

For more detailed visualizations and analysis, Homsai exposes sensor history with support for time ranges and granularity.

  • Consumption power history (W)

    • Endpoint: GET /plants/{plantUuid}/sensor-history-consumptions
    • Parameters:
      • startDate (yyyy-MM-dd'T'HH:mm): range start;
      • endDate (yyyy-MM-dd'T'HH:mm): range end;
      • granularity: seconds | minutes | hours | days.
    • Use: power curves (instantaneous or aggregated) for consumption.

  • Production power history (W)

    • Endpoint: GET /plants/{plantUuid}/sensor-history-productions
    • Parameters: same as above.
    • Use: PV (or other generator) power curves.

  • Energy history (kWh) and percentages

    • Endpoint: GET /plants/{plantUuid}/sensor-history-energy
    • Parameters:
      • startDate (yyyy-MM-dd'T'HH:mm);
      • endDate (yyyy-MM-dd'T'HH:mm).
    • Use: energy breakdown over a period (e.g. kWh per load/source, with contribution percentages).

These endpoints are the basis for:

  • advanced historical charts;
  • energy mix analysis (how much comes from PV, grid, battery);
  • custom KPIs computed on the client side.

PV plant health​

To evaluate PV performance, Homsai provides a dedicated plant health endpoint.

  • PV Health
    • Endpoint: GET /plants/{plantUuid}/pv-health
    • Typical output:
      • energy produced in a given period (kWh);
      • performance percentage compared to an expected/modelled value;
      • optional high‑level status indicators (e.g. “OK”, “Underperforming”, etc.).

Typical use cases:

  • PV diagnostics and monitoring dashboards;
  • alerts/notifications when performance drops;
  • comparing actual vs. expected production to detect degradation, shading, or faults.

Requires:

  • a valid accessToken;
  • permission PLANT_HEALTH READ;
  • plant ownership.