# Get aggregated energy statistics for a HEM system

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).

Endpoint: GET /hem_systems/{hem_system_id}/energy_stats
Version: 2.0
Security: oauth2

## Security:

  - `oauth2` (unknown)
    oauth2 scopes: home_energy:read

## Path parameters:

  - `hem_system_id` (string, required)
    The ID of the specific HEM system.

## Query parameters:

  - `start` (string, 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.

  - `end` (string, 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.

  - `resolution` (string, required)
    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.

## Header parameters:

  - `EvEnergy-Version` (number)
    Specify the version of this endpoint to use.

## Response 200:

  - `200` (unknown)
    Returns aggregated energy statistics for the HEM system.

## Response 200 fields (application/json):

  - `resolution` (string, required)
    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"

  - `start` (string, required)
    Start of the requested time range.
    Example: 2024-06-01T00:00:00Z

  - `end` (string, required)
    End of the requested time range.
    Example: 2024-06-30T23:59:59Z

  - `buckets` (array, required)
    List of aggregated energy statistics buckets.

  - `buckets.period_start` (string, required)
    Start of the aggregation period.
    Example: 2024-06-01T00:00:00Z

  - `buckets.period_end` (string, required)
    End of the aggregation period.
    Example: 2024-06-01T00:30:00Z

  - `buckets.generation_wh` (integer | null, required)
    Solar generation energy in watt-hours. Null if unavailable.
    Example: 1500

  - `buckets.consumption_wh` (integer | null, required)
    Household consumption energy in watt-hours. Null if unavailable.
    Example: 1200

  - `buckets.import_wh` (integer | null, required)
    Energy imported from the grid in watt-hours. Null if unavailable.
    Example: 600

  - `buckets.export_wh` (integer | null, required)
    Energy exported to the grid in watt-hours. Null if unavailable.
    Example: 300

  - `buckets.charge_wh` (integer | null, required)
    Battery charging energy in watt-hours. Null if unavailable.
    Example: 900

  - `buckets.discharge_wh` (integer | null, required)
    Battery discharging energy in watt-hours. Null if unavailable.
    Example: 450

  - `buckets.avg_battery_state_of_charge_percentage` (integer | null, required)
    Average battery state of charge as a percentage (0-100). Null if unavailable.
    Example: 75

  - `buckets.solar_to_home_wh` (integer | null, required)
    Energy flow from solar to home in watt-hours. Null if unavailable.
    Example: 750

  - `buckets.solar_to_battery_wh` (integer | null, required)
    Energy flow from solar to battery in watt-hours. Null if unavailable.
    Example: 500

  - `buckets.solar_to_grid_wh` (integer | null, required)
    Energy flow from solar to grid in watt-hours. Null if unavailable.
    Example: 250

  - `buckets.battery_to_home_wh` (integer | null, required)
    Energy flow from battery to home in watt-hours. Null if unavailable.
    Example: 350

  - `buckets.battery_to_grid_wh` (integer | null, required)
    Energy flow from battery to grid in watt-hours. Null if unavailable.
    Example: 100

  - `buckets.grid_to_home_wh` (integer | null, required)
    Energy flow from grid to home in watt-hours. Null if unavailable.
    Example: 100

  - `buckets.grid_to_battery_wh` (integer | null, required)
    Energy flow from grid to battery in watt-hours. Null if unavailable.
    Example: 50

## Response 200 headers (application/json):

  - `EvEnergy-Version` (number)
    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.
    Enum: "2"

  - `X-RateLimit-Limit` (number)
    The maximum number of requests that can be made to this endpoint per hour. Defaults to 1000 but may vary per client.

  - `X-RateLimit-Remaining` (number)
    The number of requests remaining until this client's rate limit is reached.

  - `RetryAfter` (number)
    The number of seconds until this client's requests will not be rate limited.

## Response 400:

  - `400` (unknown)
    A problem with the request's parameters prevented it being fulfilled.

## Response 400 fields (application/problem+json):

  - `type` (string)
    Example: https://api.ev.energy/v2/problems/example-problem/

  - `status` (number)
    Example: 400

  - `title` (string, required)
    Example: Short description

  - `detail` (string, required)
    Example: Long, more specific description.

  - `instance` (string)
    Example: https://api.ev.energy/v2/users/user01HN2P75GBNFRJPCZJXEFVXH5E

  - `notification` (object)
    Something that the user should be informed about.

  - `notification.id` (string, required)
    Unique identifier for the Notification
    Example: notf67O36PLTFDB57M0E5L33JZLGM0

  - `notification.url` (string, required)
    Example: https://api.ev.energy/notifications/notf67O36PLTFDB57M0E5L33JZLGM0

  - `notification.message_id` (string, required)
    Internal identifier for this notification type. E.g. 'ERR0023'

  - `notification.category` (string, required)
    Category of this notification type
    Enum: "ACTIONABLE", "SERVICE", "RETRY", "MARKETING", "INTERNAL"

  - `notification.event_time` (string, required)
    The timestamp of the event described by this notification

  - `notification.short_text_title` (string, required)
    Short title for the notification

  - `notification.short_text_body` (string, required)
    Short description of the event being notified

  - `notification.detail_page_title` (string, required)
    Title of a help page giving more information about this notification

  - `notification.detail_page_body` (string, required)
    Text of a help page giving more information about this notification

  - `notification.external_link` (string | null, required)
    URL of a web page giving further information about this notification

  - `notification.external_button_label` (string, required)
    Text to be displayed on a button leading to the external_link location

  - `notification.read_at` (string)
    When the user examined the contents of this notification

  - `notification.resolved_at` (string)
    When the problem associated with this notification was resolved

## Response 400 headers (application/problem+json):

  - `EvEnergy-Version` (number)
    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.
    Enum: "2"

  - `X-RateLimit-Limit` (number)
    The maximum number of requests that can be made to this endpoint per hour. Defaults to 1000 but may vary per client.

  - `X-RateLimit-Remaining` (number)
    The number of requests remaining until this client's rate limit is reached.

## Response 401:

  - `401` (unknown)
    You need to authorise requests to access this resource.

## Response 401 fields (application/problem+json):

  - `status` (number)
    Example: 401

  - `title` (string, required)
    Example: Unauthorized

  - `detail` (string, required)
    Example: Authentication credentials were not provided.

## Response 401 headers (application/problem+json):

  - `EvEnergy-Version` (number)
    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.
    Enum: "2"

  - `X-RateLimit-Limit` (number)
    The maximum number of requests that can be made to this endpoint per hour. Defaults to 1000 but may vary per client.

  - `X-RateLimit-Remaining` (number)
    The number of requests remaining until this client's rate limit is reached.

  - `RetryAfter` (number)
    The number of seconds until this client's requests will not be rate limited.

## Response 403:

  - `403` (unknown)
    You do not have permission to perform this action.

## Response 403 fields (application/problem+json):

  - `status` (number)
    Example: 403

  - `title` (string, required)
    Example: Forbidden

  - `detail` (string, required)
    Example: You do not have permission to perform this action.

## Response 403 headers (application/problem+json):

  - `EvEnergy-Version` (number)
    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.
    Enum: "2"

  - `X-RateLimit-Limit` (number)
    The maximum number of requests that can be made to this endpoint per hour. Defaults to 1000 but may vary per client.

  - `X-RateLimit-Remaining` (number)
    The number of requests remaining until this client's rate limit is reached.

  - `RetryAfter` (number)
    The number of seconds until this client's requests will not be rate limited.

## Response 404:

  - `404` (unknown)
    This resource either does not exist or the client is not authorized to access it.

## Response 404 fields (application/problem+json):

  - `status` (number)
    Example: 404

  - `title` (string, required)
    Example: Not found

  - `detail` (string, required)
    Example: Resource does not exist or cannot be accessed.

## Response 404 headers (application/problem+json):

  - `EvEnergy-Version` (number)
    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.
    Enum: "2"

  - `X-RateLimit-Limit` (number)
    The maximum number of requests that can be made to this endpoint per hour. Defaults to 1000 but may vary per client.

  - `X-RateLimit-Remaining` (number)
    The number of requests remaining until this client's rate limit is reached.

  - `RetryAfter` (number)
    The number of seconds until this client's requests will not be rate limited.

## Response 406:

  - `406` (unknown)
    Could not satisfy the request Accept header.

## Response 406 fields (application/problem+json):

  - `status` (number)
    Example: 406

  - `title` (string, required)
    Example: Not Acceptable

  - `detail` (string, required)
    Example: Could not satisfy the request Accept header.

## Response 406 headers (application/problem+json):

  - `EvEnergy-Version` (number)
    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.
    Enum: "2"

  - `X-RateLimit-Limit` (number)
    The maximum number of requests that can be made to this endpoint per hour. Defaults to 1000 but may vary per client.

  - `X-RateLimit-Remaining` (number)
    The number of requests remaining until this client's rate limit is reached.

  - `RetryAfter` (number)
    The number of seconds until this client's requests will not be rate limited.

## Response 429:

  - `429` (unknown)
    The client has exceeded its rate limit.

## Response 429 fields (application/problem+json):

  - `type` (string)
    Example: https://api.ev.energy/v2/problems/example-problem/

  - `status` (number)
    Example: 400

  - `title` (string, required)
    Example: Short description

  - `detail` (string, required)
    Example: Long, more specific description.

  - `instance` (string)
    Example: https://api.ev.energy/v2/users/user01HN2P75GBNFRJPCZJXEFVXH5E

  - `notification` (object)
    Something that the user should be informed about.

  - `notification.id` (string, required)
    Unique identifier for the Notification
    Example: notf67O36PLTFDB57M0E5L33JZLGM0

  - `notification.url` (string, required)
    Example: https://api.ev.energy/notifications/notf67O36PLTFDB57M0E5L33JZLGM0

  - `notification.message_id` (string, required)
    Internal identifier for this notification type. E.g. 'ERR0023'

  - `notification.category` (string, required)
    Category of this notification type
    Enum: "ACTIONABLE", "SERVICE", "RETRY", "MARKETING", "INTERNAL"

  - `notification.event_time` (string, required)
    The timestamp of the event described by this notification

  - `notification.short_text_title` (string, required)
    Short title for the notification

  - `notification.short_text_body` (string, required)
    Short description of the event being notified

  - `notification.detail_page_title` (string, required)
    Title of a help page giving more information about this notification

  - `notification.detail_page_body` (string, required)
    Text of a help page giving more information about this notification

  - `notification.external_link` (string | null, required)
    URL of a web page giving further information about this notification

  - `notification.external_button_label` (string, required)
    Text to be displayed on a button leading to the external_link location

  - `notification.read_at` (string)
    When the user examined the contents of this notification

  - `notification.resolved_at` (string)
    When the problem associated with this notification was resolved

## Response 429 headers (application/problem+json):

  - `EvEnergy-Version` (number)
    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.
    Enum: "2"

  - `Retry-After` (number)
    The number of seconds until this client's requests will not be rate limited.

  - `X-RateLimit-Limit` (number)
    The maximum number of requests that can be made to this endpoint per hour. Defaults to 1000 but may vary per client.

  - `X-RateLimit-Remaining` (number)
    The number of requests remaining until this client's rate limit is reached.

## Response 400 examples:

  - `Unsupported Version` (unknown)

## Response 429 examples:

  - `Example 1` (unknown)