Charging Sessions
GET /api/charging-sessions
Retrieve a list of completed charging sessions.
Parameters
Parameters should be passed as query parameters on the URL.
startTimeAfter- ISO 8601 date string to filter the list to only sessions started at or after this timestartTimeBefore- ISO 8601 date string to filter the list to only sessions started before this timeendTimeAfter- ISO 8601 date string to filter the list to only sessions ended at or after this timeendTimeBefore- ISO 8601 date string to filter the list to only sessions ended before this timenextPageCursor- When the filters match more than one page of data, pass this paramter to fetch the next pageincludeIntervals- Returns additional data about the charging session: max demand for the entire session, along with statistics for each 15-minute charging interval. When this parameter is included, an individual api key is limited to 1 concurrent request at a time.includeTouEnergy- Returns energy usage grouped into time of use periods for each sessionsiteIds- Site IDs, which can be retrieved from the /sites endpoint, to filter for. To pass multiple site IDs, add them to the query parameters like this:siteIds[]=101&siteIds[]=102chargerIds- Charger IDs, which can be retrieved from the /sites endpoint, to filter for. To pass multiple site IDs, add them to the query parameters like this:chargerIds[]=101&chargerIds[]=102
Response
The JSON response will contain a data field with a list of charging sessions matching the filters, and a pagination field containing pagination details.
{
data: {
id: number;
startTime: string; // ISO 8601 format
endTime: string; // ISO 8601 format
updatedAt: string; // ISO 8601 format
durationSeconds: number;
energyDeliveredKwh: number;
averageDemandKw: number;
socStartPercent: number | null;
socEndPercent: number | null;
maxDemandKw: number | null;
ocppIdTag: string | null;
tags: string[];
// Only defined if includeIntervals=true. Session statistics, grouped into 15-minute intervals.
intervals: {
id: string;
intervalStartTime: string; // ISO 8601 format
intervalEndTime: string; // ISO 8601 format
socStartPercent: number | null;
socEndPercent: number | null;
energyDeliveredKwh: number;
maxDemandKw: number;
averageDemandKw: number;
}[] | null;
// Only defined if includeTouEnergy=true. Energy usage grouped into time-of-use period buckets.
touEnergy: {
timeOfUsePeriodName: string;
energyKwh: number;
}[] | null;
site: {
id: number;
name: string;
locationId: string | null; // A unique identification number for a site, provided by a utility
};
charger: {
id: number;
name: string;
manufacturer: string | null;
model: string | null;
networkServiceProvider: string;
chargerType: string;
serialNumber: string | null;
numberOfPorts: number;
latitude: number | null;
longitude: number | null;
externalId: string | null;
ocppId: string | null;
};
port: {
id: number;
name: string;
portNumber: number;
maximumPowerKw: number | null;
};
vehicle: {
id: number;
name: string | null;
vin: string | null;
make: string | null;
model: string | null;
} | null;
rfid: {
id: number;
name: string | null;
} | null;
customer: {
name: string
} | null;
organization: {
id: number;
name: string;
};
ocppTransactionId: number | null; // The ID reported from the charger to identify messages related to the charging session
}[];
pagination: {
hasNextPage: boolean;
nextPageCursor: string | null;
};
};Example request and response
Request:
curl "https://api.getflipturn.com/api/charging-sessions?startTimeAfter=2023-03-24T01:18:05.000Z&includeIntervals=true" -H "Authorization: Bearer {token}"Response:
{
"data": [
{
"id": 428177,
"startTime": "2023-08-29T22:57:46.479Z",
"endTime": "2023-08-30T01:00:07.321Z",
"updatedAt": "2023-08-30T01:00:07.321Z",
"durationSeconds": 7341,
"socStartPercent": 14,
"socEndPercent": 50,
"energyDeliveredKwh": 78.775,
"averageDemandKw": 10.0,
"maxDemandKw": 12,
"intervals": [...],
"ocppIdTag": "demo-id-tag-0",
"tags": ['ABC Trucking', 'XYZ Trucking'],
"site": { "id": 13, "name": "Long Beach", "locationId": null },
"charger": {
"id": 53, "name": "Long Beach 1", "manufacturer": "ABB", "model": "AC Wall Box",
"networkServiceProvider": "Flipturn", "chargerType": "DCFC", "numberOfPorts": 1,
"serialNumber": "DEMO-NUMBER", "latitude": 1.0, "longitude": 1.0,
"externalId": "STATION-001", "ocppId": "CHARGER-001"
},
"port": { "id": 650244, "name": "Port 1", "portNumber": 1, "maximumPowerKw": 180},
"vehicle": {
"id": 22541553,
"make": "Make",
"model": "Model",
"name": "9876",
"vin": "demo-vin-0"
},
"customer": {
"name": "Electric Fleet Transportation"
},
"organization": {
"id": 1,
"name": "Fleet Management Corp"
}
}
],
"pagination": {
"hasNextPage": true,
"nextPageCursor": "NDMyNDc2"
}
}Synchronizing charging sessions into an external system
If your goal is to continuously import charging sessions into a system like a data warehouse, you may set up a recurring job to import any new charging sessions that are in Flipturn. It's important to ensure that you don't double insert any charging sessions or miss one.
We recommend splitting this into two phases:
Backfill all historical sessions
Poll for new sessions
Backfill all historical sessions
In order to export all sessions, the first request to the charging sessions endpoint should have no filter parameters. Then, every subsequent request will take the nextPageCursor from the prior response and add that to the next request.
Assume the first request returned:
{
"data": [
{ // 20 items },
]
"pagination": {
"hasNextPage": true,
"nextPageCursor": "NDMyNDc2"
}
}The second request should look like:
/api/charging-sessions?nextPageCursor=NDMyNDc2Repeat this process until you receive a response where pagination.hasNextPage is false.
Poll for new sessions
Once all the historical sessions have been exported, you can continually poll the API to fetch sessions that have completed since the last request. Each request, you should keep track of the latest endTimestamp you've seen so far, and pass that in to endTimeAfter:
/api/charging-sessions?endTimeAfter=2023-08-30T01:00:07.321ZAvoiding double-inserting
Instead of keeping track of the latest endTimestamp, some users might prefer to generate an endTimeAfter relative to when they're sending the request. For example, if you poll for new sessions every 30s, each request could set endTimeAfter to a timestamp slightly more than 30s ago to account for clock skew.
However, one risk of this buffer is it's possible to see a session that you've already exported. To help deduplicate, each charging session has a unique id, so it's recommended to use this as a unique key to ensure you don't insert the same charging session twice.
Last updated