ACN-Data

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.

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 <site_id> with the identifier of the site you want to gather data from.

Without time series:

https://ev.caltech.edu/api/v1/sessions/<site_id>

With time series:

https://ev.caltech.edu/api/v1/sessions/<site_id>/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. <, <=, ==, >, >=. 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:

https://ev.caltech.edu/api/v1/sessions/caltech?
where=connectionTime>="Wed, 1 May 2019 00:00:00 GMT"
and connectionTime<="Thu, 2 May 2019 00:00:00 GMT"
&pretty

To only get sessions from a certain user you can use:

https://ev.caltech.edu/api/v1/sessions/caltech?userID="000000556"&pretty

To get all sessions for which over 10 kWh were delivered you can use

https://ev.caltech.edu/api/v1/sessions/caltech?where=kWhDelivered>=10&pretty

Sorting

You can sort the results of a query using the sort argument. For example to get sessions sorted in descending order by connectionTime you could use:

https://ev.caltech.edu/api/v1/sessions/caltech?sort=connectionTime&pretty

By default sorting is is descending order. To instead sort in ascending order, you can append a - sign before the field, for example:

https://ev.caltech.edu/api/v1/sessions/caltech?sort=-connectionTime&pretty

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.

The following is the _links section returned from the query

https://ev.caltech.edu/api/v1/sessions/caltech?userID="000000556"&pretty

"_links": {
    "parent": {
        "title": "home",
        "href": "/"
    },
    "self": {
        "title": "sessions/caltech",
        "href": "sessions/caltech?where=userID==\"000000556\"&pretty="
    },
    "next": {
        "title": "next page",
        "href": "sessions/caltech?where=userID==\"000000556\"&page=2&pretty="
    },
    "last": {
        "title": "last page",
        "href": "sessions/caltech?where=userID==\"000000556\"&page=2&pretty="
    }
},
                                

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.

Citing the Dataset

If you use ACN-Data in published work, we ask that you cite ACN-Data: Analysis and Applications of an Open EV Charging Dataset so others can find and use the dataset as well.

@inproceedings{lee_acndata_2019,
  author = {Lee, Zachary J. and Li, Tongxin, and Low, Steven H.},
  title = { {ACN}-{Data}: {Analysis} and {Applications} of an {Open} {EV} {Charging} {Dataset} },
  booktitle = {Proceedings of the Tenth International Conference on Future Energy Systems},
  series = {e-Energy '19},
  month = jun,
  year = {2019},
  location = {Phoenix, Arizona}
}