ABRP / Iternio Telemetry API Usage with Python

Introduction

This repository provides a Python script template for interacting with the ABRP / Iternio Telemetry API : abrp_vehicle_telemetry.py.

According to ABRP (A Better Route Planner):

ABetterRouteplanner is the world's most popular consumer EV routeplanner - both for beginner and experienced EV drivers. And of course for anyone curious about EVs.

Their free Telemetry API allows uploading live vehicle data for a planned route to the ABRP mobile app (iOS/Android) or the ABRP web app.

Concretely, this script demonstrates how to send example vehicle telemetry to ABRP. By doing so, ABRP can use the data to adjust and refine route planning. The main use case of this project is to easily test the effect of live data in ABRP.

User Token and API Key management

From the API documentation :

To be able to use the API, you will need to obtain an API key and a user token for each user. The Telemetry-Only API keys are free, and get you basic access to the Telemetry API. Contact us at contact@iternio.com to receive a Telemetry API key. The API key identifies your application to our server for authentication.

There are two ways of retrieving a user token for each telemetry, which is needed to identify the user (and vehicle) to the server so we can deliver the telemetry to them. The preferred method is via OAuth2 (See OAuth2 API), which will return a user token without any data entry. It’s also acceptable to have the user retrieve a token from our Live Data Setup screen.

This repository’s script requires two environment variables, stored in a .env file:

• API_KEY → your ABRP API key
• USER_TOKEN → your ABRP user token

A .env_template file is included. Copy it to a .env and fill in your key and token values. The python-dotenv library will load it automatically when running the script.

Get your credentials

• API Key: contact Iternio by e-mail at contact@iternio.com.
• User Token: either via Iternio’s OAuth2 API (some information are available here) or directly from the ABRP mobile or web app.

Steps in the app:

1. Open ABRP Settings
2. Go to your vehicle’s settings
3. Tap Modify connections ("Modifier les connexions" in French)
4. Under Generic, tap Link (may require scrolling or swapping)
5. Your user token will appear on screen

⚠️ Remember to add both USER_TOKEN and API_KEY to your .env file (no quotes needed).

Vehicle Data Fields

The telemetry fields supported by ABRP are described in the Telemetry API documentation :

The required parameters (and expected units) in the tlm JSON object are the following, in order of priority. Nothing is strictly required, but many features in ABRP will only be usable with enough data.

High priority parameters:

• utc [s]: UTC timestamp of the data (epoch) in seconds (note, not milliseconds!)
• soc [SoC %]: State of Charge of the vehicle (what's displayed on the dashboard of the vehicle is preferred)
• power [kW]: Instantaneous power output/input to the vehicle. Power output is positive, power input is negative (charging)
• speed [km/h]: Vehicle speed
• lat [°]: Current vehicle latitude
• lon [°]: Current vehicle longitude
• is_charging [bool or 1/0]: Determines vehicle state. 0 is not charging, 1 is charging
• is_dcfc [bool or 1/0]: If is_charging, indicate if this is DC fast charging
• is_parked [bool or 1/0]: If the vehicle gear is in P (or the driver has left the car)

The lower priority parameters (and expected units) are:

• capacity [kWh]: Estimated usable battery capacity (can be given together with soh, but usually not)
• soe [kWh]: Present energy capacity of the battery, equal to SoC * capacity
• soh [%]: State of Health of the battery. 100 = no degradation
• heading [°]: Current heading of the vehicle. This will take priority over phone heading, so don't include if not accurate.
• elevation [m]: Vehicle's current elevation. If not given, will be looked up from location (but may miss 3D structures)
• ext_temp [°C]: Outside temperature measured by the vehicle
• batt_temp [°C]: Battery temperature
• voltage [V]: Battery pack voltage
• current [A]: Battery pack current (similar to power: output is positive, input (charging) is negative.)
• odometer [km]: Current odometer reading in km.
• est_battery_range [km]: Estimated remaining range of the vehicle (according to the vehicle)
• hvac_power [kW]: power usage by heating and cooling
• hvac_setpoint [°C]: current setpoint of the HVAC system
• cabin_temp [°C]: current temperature of the cabin
• tire_pressure_fl [kPa]: Front Left tire pressure
• tire_pressure_fr [kPa]: Front Right tire pressure
• tire_pressure_rl [kPa]: Rear Left tire pressure
• tire_pressure_rr [kPa]: Rear Right tire pressure

To enable vehicle individual consumption calibration, we need at least speed, power and is_charging at a rate of at least once per 10 seconds (the faster the better).

By default, abrp_vehicle_telemetry.py includes only a subset of fields. You can extend the telemetry_data dictionary with any additional parameters if needed.

How to run ?

1. Create a virtual environment and install requirements:

python -m venv .venv
source .venv/bin/activate    # Linux/macOS
.venv\Scripts\Activate.ps1   # Windows PowerShell
.venv\Scripts\activate.bat   # Windows cmd.exe

pip install -r requirements.txt

2. Copy .env_template to .env and add your API_KEY and USER_TOKEN.

3. If you need to add telemetry fields in the API request, you can modify the abrp_vehicle_telemetry.py script.

4. Run the script:

python abrp_vehicle_telemetry.py

Contribution

If you modify or extend the script, please run linting and formatting tools :

pip install -r requirements-dev.txt
ruff check abrp_vehicle_telemetry.py --fix
isort abrp_vehicle_telemetry.py
black abrp_vehicle_telemetry.py