Iternio Telemetry API

Created with Sketch.

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.

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 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.

The API is a standard REST API with HTTP parameters and JSON input/output. The API is versioned, albeit we are still on the first version. 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.

Common for all Telemetry API methods

The base address of the version 1 API is https://api.iternio.com/1/<method name>

You can call all methods 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).

The only common mandatory parameter is api_key=<your API key>. Almost all parameters are simple strings or numbers, except the more complicated parameters which are JSON encoded objects.

The result of each API call is always a JSON object with the following content:


KeyDescription
status"ok" - means the method did what it should.
"error" - the method failed.
resultAn object or an array returning the result from the method.

API Methods

The following methods are available in the API:


MethodDescription
tlm/get_carmodels_listReturns a list of presently supported car models. This list may be updated on a daily basis. The typecode field is used to specify the car model which the telemetry is associated.
tlm/get_next_chargeRetrieves the user's next charging goal.
tlm/sendThe main telemetry method, packaging all available car parameters as a JSON.

tlm/get_carmodels_list() method

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 code in your telemetry call.

The method has no input parameters (except the API key). The result is a JSON array of car model name and code pairs. Example call and Result:

https://api.iternio.com/1/tlm/get_carmodels_list?api_key=<your API key>

"Tesla;Model 3;Standard Range RWD (alpha)": "3standard"

tlm/get_next_charge() method

This method retrieves the user’s next charging goal for use in notifying them when their car has reached the desired charge level.

The result will contain the next charge-to goal for that user’s most recent plan:


KeyDescription
next_chargeUser's next goal charge value in percent (0-100)

Example call:

https://api.iternio.com/1/tlm/get_next_charge?api_key=<your API key>&token=<user token>

tlm/send() method

This 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.

There 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.

All 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.

The required parameters (and expected units) are:


KeyDatatypeUnitComment
utcfloatsecondsCurrent UTC timestamp in seconds
car_modelstringThe car model typecode (E.G. - the value returned by get_carmodels_list)
socfloat%State of Charge of the vehicle. (what's displayed on the dashboard of the vehicle is preferred)
speedfloatkm/hVehicle speed
latfloat°Current vehicle latitude
lonfloat°Current vehicle longitude
is_chargingint0 or 1 - determines vehicle state. 0 is not charging, 1 is charging

The optional parameter (and expected units) are:


KeyDatatypeUnitComment
powerfloatkWPower output/input to the vehicle. Power output is positive, power input is negative (charging)
sohfloat%State of Health of the battery. 100 = no degradation
elevationfloatmVehicle's current elevation
ext_tempfloat°COutside temperature measured by the vehicle
batt_tempfloat°CBattery temperature
voltagefloatVBattery pack voltage
currentfloatABattery pack current (similar to power: output is positive, input (charging) is negative.)

These parameters are added to the tlm object, and formatted as a JSON. Example call:

https://api.iternio.com/1/tlm/send?api_key=<your API key>&token=<user token>&tlm={"utc":1553807658,"soc":80.4,"soh":97.7,"speed":0,"lat":29.564,"lon":-95.025,"elevation":50,"is_charging":0,"power":13.2,"ext_temp":25,"batt_temp":25,"carmodel":"chevy:bolt:17:60:other","current":36.66,"voltage":360}

Once you’ve constructed your telemetry API usage, you can view the results by selecting the “View Live Data” display on the ABRP Planner (Show Settings > Show More Settings > View Live Data)