A Charge Session captures a complete charging event for an electric vehicle. Detailing when it started charging, when it ended, how much energy was used, and where it happened.

While the Readings API gives you snapshots of a vehicle’s state over time, the Charge Sessions API gives you a summarized view of each session. This is useful for building timelines, estimating charging costs, or tracking behavior over time.

​
How sessions are calculated

Depending on the vehicle, sessions are either calculated based on the vehicle’s Readings (most common), or measured directly by the vehicle manufacturer.

Calculated sessions are based on either power flow or changes in state of charge. We automatically select the best method based on the data available for each vehicle. However, the calculation method doesn’t affect how sessions appear to you. All sessions are normalized and reliable for most common use cases.

We calculate each vehicle’s Charge Sessions once per day. Ongoing sessions won’t show up until they are completed.

​
Activate the feature to get started

Before you can use this API, you’ll have to enable the CaptureChargeSessions Feature on an Entity of type EV. We’ll show you how to do that in this guide.

When you enable this feature, we’ll check if the Entity is compatible. In some cases, we may require the vehicle’s Battery Capacity to be set before the feature can be activated. In rare cases, the feature may not be available due to limitations from the vehicle manufacturer.

​
What you’ll need

  • Your API credentials
  • An Entity of type EV

​
Let’s try it out

1

Set the vehicle's battery capacity (optional)

You may need to set the vehicle’s Battery Capacity before sessions can be captured.

If you’re unsure whether this applies to your vehicle, you can skip this step and try enabling the feature directly. If the Battery Capacity is required, the request will return an error asking you to provide it.

You’ll need to specify the and in kW.

2

Start capturing charge sessions

You’ll have to enable an Entity Feature to start capturing Charge Sessions.

Activate the feature for your Entity, identified by its , setting to CaptureChargeSessions and to true.

Request (Body)
{
  "feature": "CaptureChargeSessions",
  "enabled": true
}
3

List Charge Sessions

  It might be time for a break.
A Charge Session may take up to 24 hours to appear after the vehicle has finished charging.

Once you’re ready, use the to List all Charge Sessions for it.

You’ll also have to specify a date. Sessions that started before this time won’t be part of the response.

​
start
string
required
Response (Body)
{
  "data": [
    {
      "id": "3c90c3cc-[...]-8dd25736052a",
      "entityId": "7ac991f9-[...]-1577b91625b5",
      "created": "2024-06-10T01:31:56Z",
      "data": {
        "start": "2024-06-09T14:35:21.384Z",
        "end": "2024-06-09T15:15:25.685Z",
        "charge": {
          "total": {
              "total": 49.2450,
              "unit": "kWh"
          },
          "averagePower": {
              "unit": "kW",
              "value": 85.7777
          },
          "start": {
              "unit": "%",
              "value": 23
          },
          "end": {
              "unit": "%",
              "value": 90
          },
        },
        "range": {
          "start": {
              "unit": "km",
              "value": 104.3498
          },
          "end": {
              "unit": "km",
              "value": 405.3132
          }
        },
        "locationMatches": [
          {
            "accuracy": 0.9,
            "location": {
              "id": "0db9516e-[...]-41de6cb46af4", 
              "label": "Home"
            }
          }
        ]
      }
    }
  ], ...
}

Caution
The object might not be available to you. However, our Location Matching feature is a privacy-friendly alternative available to all users.

​
Good to know

  • Charge Sessions are generated once every day, as long as the feature is enabled.
  • In most cases, Charge Sessions won’t be generated retroactively.
  • Unfinished Charge Sessions won’t show up.
  • Excact locations are usually hidden to protect privacy. If your use case requires exact locations, reach out to our team. In most cases, we recommend using Location Matching — a privacy-friendly alternative.