Skip to content
/
Get aggregated energy sta...

Get aggregated energy statistics for a HEM system

Request

Returns aggregated energy statistics for the HEM system over a specified time range and resolution.

The bucket grid is always contiguous, and a bucket with no underlying data is returned with null values. Requesting a resolution finer than the interval the system reports at therefore returns null buckets between the populated ones.

Returns 400 Bad Request if query parameters are invalid (missing, malformed timestamps, unsupported resolution, or misaligned boundaries).

Security
oauth2(Required scopes: home_energy:read)
Path
hem_system_idstringrequired

The ID of the specific HEM system.

Query
startstring, (date-time)required

Start of time range (ISO 8601 with timezone, e.g. 2024-06-01T00:00:00Z or 2024-05-31T23:00:00+01:00). Must be aligned to the resolution in the HEM system's timezone: a 5-minute boundary for PT5M, :00/:15/:30/:45 for PT15M, :00 or :30 for PT30M, midnight for P1D, 1st of month at midnight for P1M.

Example:start=2024-06-01T00:00:00Z
endstring, (date-time)required

End of time range (ISO 8601 with timezone, e.g. 2024-07-01T00:00:00Z or 2024-06-30T23:00:00+01:00). Must be aligned to the resolution in the HEM system's timezone: a 5-minute boundary for PT5M, :00/:15/:30/:45 for PT15M, :00 or :30 for PT30M, midnight for P1D, 1st of month at midnight for P1M.

Example:end=2024-07-01T00:00:00Z
resolutionstringrequired

Aggregation resolution: PT5M (5 minutes, max 24h window), PT15M (15 minutes, max 24h window), PT30M (30 minutes, max 24h window), P1D (1 day, max 31 days), or P1M (1 month, max 366 days). The bucket grid is always contiguous, and a bucket with no underlying data is returned with null values. Requesting a resolution finer than the interval the system reports at therefore returns null buckets between the populated ones.

Enum:"PT5M""PT15M""PT30M""P1D""P1M"
Example:resolution=P1D
Headers
EvEnergy-Versionnumber

Specify the version of this endpoint to use.

Value:2
curl -i -X GET \
  'https://developers.ev.energy/_mock/ev.energy-api-v2/hem_systems/{hem_system_id}/energy_stats?start=2024-06-01T00%3A00%3A00Z&end=2024-07-01T00%3A00%3A00Z&resolution=P1D' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'EvEnergy-Version: 2'

Responses

Returns aggregated energy statistics for the HEM system.

Headers
EvEnergy-Versionnumber

Indicates the version of the API that generated this response. If EvEnergy-Version was not specified in the request, this will be your OAuth application's default version.

Value:2
X-RateLimit-Limitnumber

The maximum number of requests that can be made to this endpoint per hour. Defaults to 1000 but may vary per client.

Default:1000
X-RateLimit-Remainingnumber

The number of requests remaining until this client's rate limit is reached.

Default:999
RetryAfternumber

The number of seconds until this client's requests will not be rate limited.

Default:3600
Bodyapplication/json
resolutionstringread-onlyrequired

The aggregation resolution: PT5M (5 minutes), PT15M (15 minutes), PT30M (30 minutes), P1D (1 day), or P1M (1 month).

Enum:"PT5M""PT15M""PT30M""P1D""P1M"
Example:"P1D"
startstring, (date-time)read-onlyrequired

Start of the requested time range.

Example:"2024-06-01T00:00:00Z"
endstring, (date-time)read-onlyrequired

End of the requested time range.

Example:"2024-06-30T23:59:59Z"
bucketsArray of objects(HEMSystemEnergyStatsBucket)read-onlyrequired

List of aggregated energy statistics buckets.

Response
{
  "resolution": "P1D",
  "start": "2024-06-01T00:00:00Z",
  "end": "2024-06-30T23:59:59Z",
  "buckets": [
    { … }
  ]
}