Overview
BatteryDB is an application which stores all the data from EIS tests run using your ReJoule device. BatteryDB provides a REST API for programmatic access to this data, which is available at https://app.rejoule.io/api/v2/.
This guide intends to describe the full process of getting access to the BatteryDB REST API, making simple API calls, and downloading test reports.
Getting access to BatteryDB
-
Navigate to BatteryDB.
-
If this is your first time, you will be redirected to the Log In page.
-
If you do not have an account, click Sign up to create a new account.
-
You can also log in using a social account.
-
Creating your API Key
-
Click your avatar in the top right corner to access your Profile page.
-
Use the navigation bar on the left to go to the API Keys page.
-
Press the New API Key button to create a new API key.
-
Give your API key a name, and optionally provide an expiration date for the API key. When you are ready press the Create API Key button.
-
Your API key is provided with a sample curl command to test it.
Warning
Your API key will only be provided at this time. Be sure to store it in a secure location.
Available Endpoints
| Endpoint | Description | URL |
|---|---|---|
| Batteries | A battery unit that can be a cell, module, or pack. | https://app.rejoule.io/api/v2/batteries/ |
| Battery types | A categorization of batteries based on manufacturer specifications. | https://app.rejoule.io/api/v2/types/batteries/ |
| BMS Tests | A test performed by a BMS device. | https://app.rejoule.io/api/v2/bms/tests/ |
| BMS Results | The collection of all BMS test results. | https://app.rejoule.io/api/v2/bms/results/ |
| BMS Files | Data files associated with BMS tests. | https://app.rejoule.io/api/v2/bms/files/ |
| DBC Files | Configuration files for interpreting BMS data. | https://app.rejoule.io/api/v2/bms/dbc/files/ |
| EIS data | The collection of all EIS test data. | https://app.rejoule.io/api/v2/eis/data/ |
| EIS devices | A ReJoule EIS measurement device. | https://app.rejoule.io/api/v2/eis/devices/ |
| EIS tests | A Test performed by a ReJoule EIS device. | https://app.rejoule.io/api/v2/eis/tests/ |
| Organizations | A user group that provides access control for BatteryDB data. | https://app.rejoule.io/api/v2/organizations/ |
| Projects | A grouping of devices, batteries, and tests for sorting and organization. | https://app.rejoule.io/api/v2/projects/ |
| Users | A user account for accessing BatteryDB. | https://app.rejoule.io/api/v2/users/ |
Query Examples
-
Find all tests that have been completed:
-
Collect all data from a specific test
-
Filter tests by a specific creation time:
-
All date-times are using ISO 8601 formatting.
Request Examples
Note
All API keys shown below are not real and should be replaced with your own API key.
Using curl
-
A GET request using curl:
-
A POST request using curl:
Using Python
-
Install the Requests and pandas Packages:
-
A simple GET request:
-
Getting all the EIS data from a test in a single pandas dataframe:
# import packages import requests import pandas as pd # instantiate variables url = f"https://app.rejoule.io/api/v2/" user_key = "User hiMWl0P2.34bbUCC53c7RmcoS9FKF2jfVqFac7jBjm" test_id = 441 # define the function we are building # the functional inputs are: the id of the test as an integer, the base url # of the database as a string, and an API key as a string def get_eis_test_data(test,url,user_key): # create the base url query to gather all EIS data for the specified test next_link = f"{url}eis/data/?test={test}" # create a list to store data as we process it rawdata = [] # this loop is to ensure we cycle through all the pages that it may take # to gather all the EIS data while next_link: # GET the data on this page r = requests.get( next_link, verify=True, headers={'Authorization': user_key}, ) # if something goes wrong we stop the function and return the broken # request if not r.ok: return r.json() # if there is a next page we store it here to ensure we loop through # all pages; otherwise, this is set to None next_link = r.json()["next"] # all results on this page are added to our data list results = r.json()["results"] rawdata = rawdata + results # we now create the dictionary that will hold our processed data data = dict() for data_point in rawdata: # we ignore data points that do not have attached frequencies such # as general test parameters or ocv data if data_point['frequency'] is None: continue if data_point["frequency"] not in data.keys(): data[data_point["frequency"]] = dict() # the data is structured by frequency and then by parameter so # data[frequency][parameter] = value data[data_point["frequency"]][data_point["parameter"]] = data_point["value"] # the dictionary of the data is then passed into pandas to create a # dataframe data_frame = pd.DataFrame(data) # the dataframe is transposed so that each frequency is a row data_frame = data_frame.T return data_frame # an example call of the function using the variables defined above df = get_all_test_data(test_id,url,user_key) -
Generating a report containing real and imaginary impedance for all tests in a given list:
- This function builds on the previous one, so be sure to define that first.
# import packages
import requests
import pandas as pd
# instantiate variables
url = f"https://app.rejoule.io/api/v2/"
user_key = "User hiMWl0P2.34bbUCC53c7RmcoS9FKF2jfVqFac7jBjm"
test_list = [105,104,103,102]
# define the function we are building
# the functional inputs are: the list of tests to be included in the report as
# a list of integers, the base url of the database as a string, and an API key
# as a string
def generate_test_report(test_list,url,user_key):
# we begin by creating our data structure
# this is a list of lists, with each list corresponding to a row of the
# dataframe
# the first row will be the header for our dataframe
data = ["battery_id"]
# these are the real and imaginary impedance names as lists
# an eis test considers 42 frequencies
zr = [f"z_real_{i}" for i in range(42)]
zi = [f"z_imag_{i}" for i in range(42)]
data = [data +zr+zi]
# loop through the test list
for test in test_list:
# get the first tests data
turl = f"{url}eis/tests/{test}/"
r = requests.get(
turl,
verify=True,
headers={'Authorization': user_key},
)
# begin building the dataframe row
row = []
# the values stored here are the primary key ids of each battery
row.append(r.json()['battery'])
# use the previous function to get the EIS data and add it to the row
sub = get_eis_test_data(test,url,user_key)
zrs = sub["z_real"].to_list()
zis = sub["z_imag"].to_list()
row = row +zrs+zis
# add each row to the overall data list
data.append(row)
# we use the data structure to create the dataframe and establish the
# header
df = pd.DataFrame(data[1:])
df.columns = data[0]
# now we cycle through the dataframe and find the battery id values for
# each battery included in the test
for i in range(df.shape[0]):
# the url is generated by the primary key stored from the test data,
# and is used to get the battery data
burl = f"{url}batteries/{df['bid'].iloc[i]}"
r = requests.get(
burl,
# verify=False,
headers={'Authorization': user_key},
)
# the primary key is now replaced with the battery id
df['bid'].iloc[i] = r.json()["battery_id"]
return df
# we run our function here using the variables defined above
eis_report = generate_test_report(test_list,url,user_key)
- Using the requests and json packages to upload bulk data to the database:
# import packages
import requests
import json
# define variables
url = f"https://app.rejoule.io/api/v2/projects/"
user_key = "User hiMWl0P2.34bbUCC53c7RmcoS9FKF2jfVqFac7jBjm"
data = [
{
"organization": 1,
"name": "project1"
},
{
"organization": 1,
"name": "project2"
},
{
"organization": 1,
"name": "project3"
},
{
"organization": 1,
"name": "project4"
},
]
data = json.dumps(data)
# data is a json dump of a list of json like dictionaries, each one satisfying
# the upload requirements for the endpoint
r = requests.post(
url,
verify=True,
headers={'Authorization': user_key, 'Content-Type': 'application/json'},
data=data,
)