Documentation

Historical Energy Data

Copy page

TL;DR

• GET /energy-data/daily?date=2025-03-15 — 5-minute resolution with per-device consumption and activity windows
• GET /energy-data/period?date=2025-03-15&period=weekly — aggregated by day/week/month/year
• Energy in Wh, power readings in W, all money values (costs, savings, revenue) in cents — divide by 100 for display
• Timestamps are UTC (...Z) — convert to the user's timezone in your frontend
• The requested date is a calendar day in the home's timezone (fixed when the home is created, default Europe/Berlin) — see Timezone behaviour
• No data for a date? Returns 200 with zeroes, not 404

The Historical Energy Data endpoints provide aggregated energy metrics for a user's home over past time periods. While Live Telemetry pushes real-time device state updates via Event Hubs, these REST endpoints let you retrieve processed historical data — including grid consumption, solar production, battery activity, device-level breakdowns, and cost calculations.

---

Live Telemetry vs. Historical Energy Data

	Live Telemetry (Event Hub)	Historical Energy Data (REST)
Delivery model	Push — events stream as they occur	Pull — you request data for a specific date
Resolution	Per-change (seconds)	5-minute intervals (daily) or day/week/month aggregates
Data scope	Current device capabilities	Energy totals, costs, savings, device activity windows
Use case	Dashboards, monitoring, alerting	Reports, analytics, billing, energy insights

Use both together: Live Telemetry for real-time monitoring and Historical Energy Data for retrospective analysis and reporting.

---

Endpoints overview

Method	Endpoint	Description
GET	/v1/users/{userId}/energy-data/daily	Daily data with 5-minute resolution intervals
GET	/v1/users/{userId}/energy-data/period	Aggregated data for weekly, monthly, or yearly periods

Both endpoints return energy totals in watt-hours (Wh), monetary cost and savings figures in cents (minor unit of the user's tariff currency), and per-device breakdowns.

---

Authentication

These endpoints use the same authentication as all Connect API endpoints:

• Scheme: Bearer token (JWT)
• Scope: connect_api
• User context: The {userId} path parameter is your external user ID (the same ID you use when provisioning users)

See Authentication for details on obtaining a token.

---

Daily energy data

Code
GET /v1/users/{userId}/energy-data/daily?date={date}

Returns energy data for a single day with 5-minute resolution intervals, per-device consumption breakdowns, and device activity windows.

Request parameters

Parameter	Location	Type	Required	Description
userId	path	string	yes	External user ID
date	query	string	yes	Date in yyyy-MM-dd format

Response

Code
{
  "date": "2025-03-15",
  "summary": {
    "gridConsumptionWh": 8450,
    "gridFeedInWh": 12300,
    "productionWh": 18750,
    "batteryChargedWh": 5200,
    "batteryDischargedWh": 3100,
    "costs": {
      "gridConsumptionCosts": 253,
      "gridFeedInRevenue": 98,
      "totalSavings": 412,
      "pvSavings": 345
    }
  },
  "intervals": [
    {
      "timestamp": "2025-03-15T06:00:00Z",
      "gridConsumptionWatt": 520,
      "productionWatt": 0,
      "batteryStateOfChargePercent": 45,
      "batteryChargingWatt": null,
      "batteryDischargingWatt": 200,
      "devices": [
        {
          "deviceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "name": "Wallbox",
          "category": "Wallbox",
          "consumptionWh": 150
        }
      ]
    }
  ],
  "devices": [
    {
      "deviceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Wallbox",
      "category": "Wallbox",
      "totalConsumptionWh": 11200,
      "costs": 336,
      "savings": 180,
      "activities": [
        {
          "startedAt": "2025-03-15T08:30:00Z",
          "endedAt": "2025-03-15T11:45:00Z",
          "consumptionWh": 9500,
          "durationMinutes": 195,
          "costs": 285
        }
      ]
    }
  ]
}

Response fields

Field	Type	Description
date	string	The requested date (yyyy-MM-dd)
summary	object	Aggregated energy totals and costs for the day
intervals	array	5-minute resolution data points with power readings (Watt)
devices	array	Per-device energy summary with activity windows

---

Period energy data

Code
GET /v1/users/{userId}/energy-data/period?date={date}&period={period}

Returns aggregated energy data for a longer time period (weekly, monthly, or yearly), broken down into sub-intervals (e.g., individual days within a week).

Request parameters

Parameter	Location	Type	Required	Description
userId	path	string	yes	External user ID
date	query	string	yes	Anchor date in yyyy-MM-dd format
period	query	string	yes	Aggregation period: weekly, monthly, yearly

Response

Code
{
  "date": "2025-03-15",
  "period": "weekly",
  "summary": {
    "gridConsumptionWh": 58200,
    "gridFeedInWh": 85400,
    "productionWh": 132000,
    "batteryChargedWh": 36500,
    "batteryDischargedWh": 28700,
    "costs": {
      "gridConsumptionCosts": 1746,
      "gridFeedInRevenue": 683,
      "totalSavings": 2850,
      "pvSavings": 2210
    }
  },
  "consolidatedIntervals": [
    {
      "date": "2025-03-10",
      "gridConsumptionWh": 8200,
      "gridFeedInWh": 12100,
      "productionWh": 18800,
      "batteryChargedWh": 5100,
      "batteryDischargedWh": 4050,
      "costs": {
        "gridConsumptionCosts": 246,
        "gridFeedInRevenue": 97,
        "totalSavings": 405,
        "pvSavings": 315
      }
    }
  ],
  "devices": [
    {
      "deviceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Wallbox",
      "category": "Wallbox",
      "totalConsumptionWh": 35000,
      "costs": 1050,
      "savings": 560,
      "activities": null
    }
  ]
}

Response fields

Field	Type	Description
date	string	The anchor date (yyyy-MM-dd)
period	string	The requested period (weekly, monthly, yearly)
summary	object	Aggregated energy totals and costs across the entire period
consolidatedIntervals	array	Sub-period aggregates (e.g., one entry per day in a weekly view)
devices	array	Per-device totals for the period (no activity windows)

---

Timezone behaviour

Two distinct timezone concepts apply to these endpoints — keep them apart:

• Returned timestamps are always UTC. Every timestamp, startedAt, and endedAt value is the true UTC instant of the underlying measurement, serialised as ISO 8601 with a trailing Z (e.g. 2025-03-15T06:00:00Z). Convert to the user's local timezone in your own application.
• The requested date is a day in the home's timezone. The date parameter (and the period anchor date) selects a calendar day from midnight to midnight in the home's timezone, which is why a day's intervals do not start at 00:00Z.

The home's timezone is fixed when the home is created (default Europe/Berlin) — see Home timezone for how it is set.

---

Response field reference

Summary

Energy totals for the requested period. All energy values are in watt-hours (Wh).

Field	Type	Description
gridConsumptionWh	decimal	Total energy drawn from the grid
gridFeedInWh	decimal	Total energy fed into the grid
productionWh	decimal?	Total solar production (null if no solar system)
batteryChargedWh	decimal	Total energy charged into the battery
batteryDischargedWh	decimal	Total energy discharged from the battery
costs	object	Cost and savings breakdown (see Costs)

Costs

All amounts in this object are in cents (minor currency unit of the user's configured tariff, e.g. euro cents). Values are decimal so fractional cents can appear where the backend uses them.

Field	Type	Description
gridConsumptionCosts	decimal	Cost of grid-drawn energy, in cents
gridFeedInRevenue	decimal	Revenue from feed-in, in cents
totalSavings	decimal	Total savings (self-consumption + feed-in), in cents
pvSavings	decimal	PV self-consumption savings, in cents

Daily interval (5-minute resolution)

Each interval represents a 5-minute window. Power values are in Watt (instantaneous readings).

Field	Type	Description
timestamp	string	ISO 8601 UTC timestamp
gridConsumptionWatt	int	Grid power draw in Watt
productionWatt	int?	Solar production in Watt
batteryStateOfChargePercent	int?	Battery state of charge (0–100%)
batteryChargingWatt	int?	Battery charging power in Watt
batteryDischargingWatt	int?	Battery discharging power in Watt
devices	array	Per-device consumption for this interval

Device interval

Field	Type	Description
deviceId	string	Device ID (GUID)
name	string	Device display name
category	string	Device category (e.g., Wallbox, HeatPump, Switch)
consumptionWh	decimal	Device consumption in Wh for this interval

Consolidated interval (period aggregates)

Each interval represents one sub-period (e.g., a single day within a weekly view). All energy values are in watt-hours (Wh).

Field	Type	Description
date	string	Date of this sub-period (yyyy-MM-dd)
gridConsumptionWh	decimal	Grid consumption in Wh
gridFeedInWh	decimal	Grid feed-in in Wh
productionWh	decimal?	Solar production in Wh
batteryChargedWh	decimal	Battery charged in Wh
batteryDischargedWh	decimal	Battery discharged in Wh
costs	object	Cost breakdown for this sub-period (amounts in cents, see Costs)

Device

Per-device energy summary for the requested period.

Field	Type	Description
deviceId	string	Device ID (GUID)
name	string	Device display name
category	string	Device category (e.g., Wallbox, HeatPump, Switch)
totalConsumptionWh	decimal	Total energy consumed by this device
costs	decimal?	Cost attributed to this device, in cents
savings	decimal?	Savings attributed to this device, in cents
activities	array?	Activity windows (daily endpoint only, null for period)

Device activity (daily only)

Activity windows show when a device was actively consuming energy during the day.

Field	Type	Description
startedAt	string	Activity start time (ISO 8601 UTC)
endedAt	string	Activity end time (ISO 8601 UTC)
consumptionWh	decimal	Total consumption during this activity
durationMinutes	int	Duration in minutes
costs	decimal?	Calculated cost for this activity window, in cents

---

Code examples

C# (.NET)

Code
using System.Net.Http.Headers;
using System.Text.Json;

var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", "YOUR_ACCESS_TOKEN");

var baseUrl = "https://connect.clever-pv.com";
var userId = "your-external-user-id";

// Daily energy data
var dailyResponse = await client.GetAsync(
    $"{baseUrl}/v1/users/{userId}/energy-data/daily?date=2025-03-15");
var dailyJson = await dailyResponse.Content.ReadAsStringAsync();
Console.WriteLine(dailyJson);

// Weekly energy data
var weeklyResponse = await client.GetAsync(
    $"{baseUrl}/v1/users/{userId}/energy-data/period?date=2025-03-15&period=weekly");
var weeklyJson = await weeklyResponse.Content.ReadAsStringAsync();
Console.WriteLine(weeklyJson);

Python

Code
import requests

base_url = "https://connect.clever-pv.com"
user_id = "your-external-user-id"
headers = {"Authorization": "Bearer YOUR_ACCESS_TOKEN"}

# Daily energy data
daily = requests.get(
    f"{base_url}/v1/users/{user_id}/energy-data/daily",
    params={"date": "2025-03-15"},
    headers=headers,
)
print(daily.json())

# Monthly energy data
monthly = requests.get(
    f"{base_url}/v1/users/{user_id}/energy-data/period",
    params={"date": "2025-03-15", "period": "monthly"},
    headers=headers,
)
print(monthly.json())

JavaScript / Node.js

Code
const baseUrl = "https://connect.clever-pv.com";
const userId = "your-external-user-id";
const headers = { Authorization: "Bearer YOUR_ACCESS_TOKEN" };

// Daily energy data
const dailyRes = await fetch(
  `${baseUrl}/v1/users/${userId}/energy-data/daily?date=2025-03-15`,
  { headers },
);
const daily = await dailyRes.json();
console.log("Summary:", daily.summary);
console.log("Intervals:", daily.intervals.length);

// Yearly energy data
const yearlyRes = await fetch(
  `${baseUrl}/v1/users/${userId}/energy-data/period?date=2025-03-15&period=yearly`,
  { headers },
);
const yearly = await yearlyRes.json();
console.log("Yearly summary:", yearly.summary);

---

Important notes

• Units: Summary and interval energy values are in watt-hours (Wh). Daily interval power readings (gridConsumptionWatt, productionWatt, etc.) are in Watt (instantaneous power, not energy). All cost and savings fields (summary.costs, consolidatedIntervals[].costs, device costs / savings, activity costs) are in cents (minor unit of the tariff currency).

• Displaying money: Divide cent values by 100 to show major units (e.g. euros) in your UI.

• Timestamps are UTC: All timestamp, startedAt, and endedAt fields are the true UTC instant in ISO 8601 with a trailing Z. Convert to the user's local timezone in your application as needed. The requested date, however, is sliced by the home's timezone (not UTC) — so a day's intervals do not start at 00:00Z. See Timezone behaviour.

• Nullable fields: Fields like productionWh, batteryStateOfChargePercent, and costs may be null when no solar system or battery is connected, or when cost data is unavailable. Always handle null values gracefully.

• Empty responses: If no data is available for the requested date, the endpoint returns 200 OK with zero values in the summary and empty arrays for intervals and devices — not 404.

• Device activities: Activity windows are only included in the daily endpoint response. The period endpoint returns null for activities on each device.

• Producer devices excluded: Only consumer devices (wallboxes, heat pumps, switches, etc.) appear in the devices array. Producer devices like solar inverters are not listed as separate devices — their production is reflected in the productionWh summary field.

• Period behavior: The date parameter serves as an anchor date. For weekly, data covers the week containing that date. For monthly, the full month. For yearly, the full year.

• Correlating with Live Telemetry: The deviceId values match between Historical Energy Data and Live Telemetry events. Use Historical Energy Data for daily/weekly/monthly reports and Live Telemetry for real-time dashboards.