ACN-Data

About the Dataset

ACN-Data exists to help researchers access real data around electric vehicle
charging. The dataset is made possible by a close collaboration with
PowerFlex Systems which operates Adaptive Charging
Networks around the United States.

Each entry in the dataset contains information about a single charging session.
For more details on the data collected see the Fields and Sites tabs above.

There are 3 ways to access the dataset.

Web Interface - A simple way to download data as JSON files.

REST API - A more flexible way to access data.

Python API Client - A simple client for using the API in Python.

This interface provides an easy way to explore and download the acndata dataset.
Simply fill in the fields you would like to filter over and the session count above
the
form will update. When you are happy with your filters, click the download button
below
to get a json file with all the relevant charging sessions.

Site

From

To

Minimum Energy (kWh)

Sessions Found:

-

The ACN-Data API provides programmatic access to the dataset.

Authentication

We ask all users to register in order to use the ACN-Data API. This helps us keep track
of how much the dataset is being used and protect it from bad actors. To get an access
token please register below.
For the following examples, if your browser prompts you for a username and password,
enter your token as the username and leave the password blank.
DO NOT enter the username and password you used to register, this will not work.

Sessions API

Endpoints

The ACN-Data session API provides two end-points. The first gives access to all fields
EXCEPT time series while the second give access to all fields. To use each endpoint
replace &ltsite_id&gt with the identifier of the site you want to gather
data from.

Without time series:

https://ev.caltech.edu/api/v1/sessions/&ltsite_id&gt

With time series:

https://ev.caltech.edu/api/v1/sessions/&ltsite_id&gt/ts

Only use the /ts endpoint when you really need time series data, as it can be slow and
bogs down our servers.

Arguments

Arguments allow you to have more control over which sessions are returned. Three
args are currently supported, pretty, where, and sort. To use arguments, use a
? between the endpoint and the first argument. If you wish to use multiple
arguments use & between each argument.

Pretty

The pretty argument formats the json returned by the API request in a human
readable way.

Filtering

Filtering allows you to limit the sessions which are returned from an API call. Filters
are applied using the where parameter. You can filter on most session
fields using standard comparators, i.e. &lt, &lt=,
==, &gt, &gt=. You can also chain conditions
using the and and or keywords.
For example we can get only sessions from Caltech which started between May 1, 2019 and
May 2, 2019 using the query:

HATEOAS

Hypermedia As The Engine Of Application
State (HATEOAS)
is a feature of REST APIs which makes it easier for clients to understand how to
interact with the API. For
the ACN-Data API, HATEOAS information is stored under _links in the json
response and contains
links to allow the client to navigate the API. The easiest way to understand this is to
look at an example.

Each of these entries describes a link relative to the API base, in this case

https://ev.caltech.edu/api/v1/

The most important of these links is next which tells the client what link
to follow to get
the next page of results. The API uses pagination to make responses shorter. For the
non-time series endpoint
requests are limited to 25 sessions per page, for time series the limit is 1 per page.
To get all sessions which
match its request, the client should follow all next links until the next
section is
no longer included in _links. This indicates the client has accessed all
relevant data.
Information about pagination can also been seen in the _meta section of the
response. For example

"_meta": {
"page": 1,
"max_results": 25,
"total": 50
}

This indicates that we are currently on page 1 of the results, each page has a maximum
of 25 sessions,
and there are 50 total sessions which match our query. By simple math, there are 2 pages
(50/25).

Python Client

While the raw ACN-Data API provides flexibility to those who need it. The simplest way
to interact with ACN-Data programmatically is to use our Python client. This client is
packaged as part of the acnportal library available at https://github.com/zach401/acnportal.

Field

Type

Description

_id

string

Unique identifier of the session record.

chargingCurrent

timeseries

Time series of the measured current draw of the EVSE during the session.

clusterID

string

Unique identifier for a subset of EVSEs at a site, such as a single
garage.

connectionTime

datetime*

Time when the EV plugged in.

disconnectTime

datetime*

Time when the EV unplugged.

doneChargingTime

datetime*

Time when of the last non-zero current draw recorded.

kWhDelivered

float

Amount of energy delivered during the session.

pilotSignal

timeseries

Time series of the pilot signals passed to the EVSE during the session.

sessionID

string

Unique identifier for the session.

siteID

string

Unique identifier for the site.

spaceID

string

Unique identifier of the parking space.

stationID

string

Unique identifier of the EVSE.

timezone

string

Timezone of the site. Based on pytz format.

userID

string

Unique identifier of the user. Not provided for sessions which are not
claimed using the mobile app.

userInputs

list(User Input)

Inputs provided by the user. Since inputs can be changed over time, there
can be multiple user input objects in the list.

*datetime fields are stored as strings according to the RFC 1123 format. All
all datetimes are in UTC (GMT) see timezone field for the correct timezone of the
site.

User Inputs

Field

Type

Description

WhPerMile

float

Efficiency of the EV in Wh per mile.

kWhRequested

float

Energy requested by the user in kWh.

milesRequested

float

Number of miles requested by the user.

minutesAvailable

float

Length of the session as estimated by the user.

modifiedAt

datetime*

Time this user input was provided.

paymentRequired

bool

If the user was required to pay for this session.

requestedDeparture

datetime*

User estimated departure time.

userID

string

Unique identifier for the user.

Time Series

Field

Type

Description

timestamps

list(datetime*)

List of timestamps, one per value.

pilot/current

list(float)

List of values, one per timestamp.

Name

id

Description

Caltech

caltech

A research university located in Pasadena, CA. We currently collect data
from 54 EVSEs in one campus garage. The site is open
to the public but most usage is from faculty, staff and students.

JPL

jpl

A national research lab located in La Canada, CA. This site currently has 50
EVSEs and is only open to
employees. It is indicative of a normal workplace schedule.

Office 1

office001

An office building located in the Silicon Valley area. It currently has 8
EVSEs and is used only by employees.