The Iternio Telemetry API allows your application to send data to A Better Routeplanner for use in driving with live data, and helping us improve our car modelling.
\nTo 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.
\nThere 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.
\nThe main endpoint is the send endpoint which transmits vehicle telemetry (live data) to the ABRP/Iternio servers. This data will be presented to the user and used while planning and driving with ABRP.
When telemetry data is given to us, we want to give back some data which helps you create a better user experience in your app or service. Therefore we offer also the non-telemetry-related endpoints
get_next_charge: Returns the next charge-to SoC while the user is driving, so that your app can signal the user when the charging is done or similar
\nget_latest_plan: Returns the latest plan the user has created so that your app can display it or do something with it for the benefit of the user
\nThe base address of the version 1 API is https://api.iternio.com/1/
\nYou can call all endpoints using HTTP GET or POST – both works. In both cases, the parameters have to be URLencoded, either in the URL (for GET) or in the body (for POST).
\nThe API is a standard REST API with HTTP parameters and JSON input/output. The API is versioned, and the current version is 1. When we introduce non-backwards compatible changes, we will bump the API version and run the versions in parallel as long as it is possible.
\nAuthentication is done vida the URL query parameter \"api_key=xxxx\" or the HTTP header \"Authorization\" with the value \"APIKEY xxxxx\". You can obtain API keys and more information by contacting us at contact@iternio.com.
\nThe API uses JSON objects for return values, outside of the normal HTTP status codes. HTTP status codes are only used to indicate serious errors such as invalid API key or wrong usage of the API. Everything else is returned with an HTTP 200 and an application/json payload.
\nThe return object has two mandatory fields
\nstatus: One of \"ok\", \"error\" or other more specific strings
\nresult: The actual result of the operation (list of chargers, plan, etc)
\nThis is the main method of the Iternio Telemetry API. It will respond with any errors encountered when processing the telemetry, or with the standard “status”: “ok” response if no issues were encountered.
\nIf the status is not \"ok\", then a number of errors may be indicated in the \"errors\" property of the returned JSON object.
\nThere are a number of required parameters which must be in every call to the API. Without these, we cannot provide a useful driving mode to the user. There are also optional (but highly desired) parameters which add insight to the vehicle and help with producing more accurate plans and car models.
\nAll parameters are expected to be received in metric. They will be converted for display to the user if required. The desired data rate is one point every 5 seconds, but slower rates are accepted. Less than one every 30 seconds is recommended against.
\nThe backend system works with telemetry data in batches for efficiency and to be able to merge telemetry from different sources (e.g. from the Telemetry API and GPS from the app).
\nCurrently, the system delays processing by 60 seconds to wait for all sources of telemetry to report data. A consequence of this is also that if you only send data within a 60 second window, it will not get processed until you send data outside of that window (i.e. data for the next minute).
\nThe 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.
\nHigh priority parameters:
\nutc [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:
\ncapacity [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).
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"},{"key":"value","value":"This is a secondary method for sending telemetry to the API, allowing multiple data points to be handled in a single call. The individual entries in tlm_list can contain any valid parameter in the send call.
This endpoint can handle multiple vehicles and multiple data points per vehicle. There is not a hard limit on the number of data points, but it is recommended to keep bulk packets relatively frequent to avoid too much delay in receipt & display of data.
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"},{"key":"value","value":"The Iternio route planner supports a large and growing number of EV models. Similar to the “get_carmodels” method of the planner API, this returns that list of EV models, but without all the extraneous planning details. You will need to include a car model typecode in your telemetry call.
\nThe method has no input parameters (except the API key). The result is a JSON array of car model name and typecode pairs. Example result:
\n{\n \"status\": \"ok\",\n \"result\": [\n {\n \"Tesla;Model 3;Standard Range RWD (alpha)\": \"3standard\"\n },\n {\n \"Tesla;Model 3;Standard Range Plus RWD (beta)\": \"tesla:m3:19:bt36:none\"\n },\n ...\nThis method retrieves the user’s next charging goal for use in notifying them when their car has reached the desired charge level.
\nThe result will contain the next charge-to goal [SoC %] for that user’s most recent plan:
\nResult properties:
\nExample response:
\n{\n \"status\": \"ok\",\n \"result\": {\n \"next_charge\": 86.0\n }\n}\nA token identifying the user. This token can be obtained using the live data setup guides in the ABRP app, or, preferably, using our OAuth2 API.
\n","type":"text/plain"},"key":"token","value":"This method set the user’s next charging goal [SoC %]. This can be done by an application which actively tracks the users progress along the plan, for example the ABRP app driving mode.
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"},{"key":"value","value":"A token identifying the user. This token can be obtained using the live data setup guides in the ABRP app, or, preferably, using our OAuth2 API.
\n","type":"text/plain"},"key":"token","value":"The SoC % to charge to at the next charging stop.
\n","type":"text/plain"},"key":"next_charge_to_perc","value":"73.0"}],"variable":[]}},"response":[],"_postman_id":"f3488e7e-2625-4afb-afd9-64505aabc51c"},{"name":"send_torque","id":"7fa1b5b9-ae37-4ced-8a27-f126c8dde5bf","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://api.iternio.com/1/tlm/ampera66?eml=This method set the user’s next charging goal [SoC %]. This can be done by an application which actively tracks the users progress along the plan, for example the ABRP app driving mode.
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"},{"key":"value","value":"Get the latest telemetry from a vehicle identified with a token. Returns a subset of properties from the telemetry object.
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"},{"key":"value","value":"