Iternio Route Planner API

Created with Sketch.

The Iternio EV route planner is built around the same route optimizer which powers the well-known and highly trusted ABetterRoutePlanner web app. As ABRP is developed, the same features also become available in the route planning API; new car models, weather features, charger databases etc.

To be able to use the API, you will need to obtain an API key. The pricing is simple: There is a small setup cost for new customers and thereafter we charge per successful plan delivered by the API, that is specifically the plan method documented below. All other calls are free of charge. Contact us to discuss your need and obtain an API key.

The API is a standard REST API with HTTP parameters and JSON output. The API is versioned, albeit there 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 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 result 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
get_carmodelsReturns 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 used for planning..
get_chargersReturns chargers from the Iternio database of a given type and in a given neighborhood of a center point. This is typically called repeatedly as the user pans around in a map.
Note that in most cases, Iternio does not own this charger data - it is synchronized from other charger databases with permission. However, to display these chargers in your application, you may need to seek the permission from the original charger database provider.
get_outlet_typesReturns list of EV planning API charger outlet types.
planThe main planning/route optimization method. This method has a large set of optional parameters which may or may not be specified depending on the detail level of the application. The output is up to three suggested routes matching the given parameters and details such as estimated SoC %, elevation, lat-lon coordinates, turn instruction and much more.
get_carmodels() method

The Iternio route planner supports a large and growing number of EV models. These are internally represented by an advanced model which captures each individual model’s properties when it comes to consumption in relation to speed, elevation, weather, and charging speed for different types of chargers and car SoC. To get a list of the currently supported car models, use the get_carmodels call.

The method has no input parameters (except the API key). The result is a JSON array of car model objects, each object consisting of

KeyUnitComment
nameFull text name of the car model, hierarchically split by semicolons.
typecodeThe car model typecode used by e.g. the plan method.
ref_consWh/kmThe default reference consumption for the specific car model. Needs to be provided together with the typecode to the plan method.
rec_max_speedkm/hA recommended max speed for free speed highways. Should also be provided to the plan method.
fast_chargersComma-separated text string of supported fast chargers (including those with official adapters).
rec_fast_chargersRecommended default fast chargers.

Example call:

https://api.iternio.com/1/get_carmodels?api_key=<your API key>
get_chargers() method

The EV routes produced by the Iternio planner uses the internal database of chargers at Iternio. This database, in turn, consists mostly of data from various chargers database around the world, which we have received permission to use for the ABetterRoutePlanner service. To display these chargers in your application, you may have to receive the explicit permission from the original database owner.

The planner will plan routes using the chargers in this database – if you want to include your charger database chargers in planning, these will have to be imported/synchronized to the Iternio database first.

The get_chargers method will return a set of chargers according to filter parameters around a given lat,lon coordinate. The input parameters are as follows:

KeyDatatype and UnitDescription
latfloatThe latitude of the center of the charger search.
lonfloatThe longitude of the center of the charger search.
typesstringcomma-separated list of charger types. Available types include "SC" (Tesla Supercharger, only one with capital letters), "ccs", "chademo", "type2" and many more.
radiusfloat [meter]The search radius.
idscomma-separated ints[Optional] One or more charger IDs. If given, no other parameters are needed.
limitinteger[Optional] Maximum number of results, default (and max) is 5000.
The chargers will be sorted in order of power.
allowed_dbscomma-separated list of charger database names[Optional] If given, this limits the chargers returned to be from the specified set of charger databases.

The result will include at most 5000 chargers.The result is an array consisting of charger objects with the following information:

KeyDatatype and unitDescription
idintegerInternal Iternio charger database ID. Used to refer to specific chargers in plan method calls.
statusstringOne of
"OPEN" - meaning open and functional
"LIMITED" - reported broken or with limited opening hours. Will not be used in planning unless explicitly included as a waypoint.
"CONSTRUCTION", "CLOSED", etc - not open.
namestringThe human readable name of the charger.
addressstringThe street address of the charger.
commentstringA text comment about the charger.
latfloatThe latitude.
lonfloatThe longitude.
outletsarrayAn array of outlet objects for this charger.
locationidstringThe original id of the charger from the source database in format [database name]_[original id]

Outlet objects contain

KeyDatatype and UnitDescription
typestringThe outlet type (e.g. "ccs")
powerfloat [kW]The maximum power of the charger outlet.
stallsintegerThe number of stalls for this outlet type.

Example call:

https://api.iternio.com/1/get_chargers?api_key=<your API key>&lat=54.0&lon=10.0&types=ccs&radius=30000
get_outlet_types() method

This method is mostly intended for API developers who want to get the full list of our charger outlet types. For customer where we import a charger database and convert connector/EVSE/outlet types to our types we also provide a translation table.

Example call:

https://api.iternio.com/1/get_outlet_types?api_key=<your API key>
plan() method

This is the main method of the Iternio Route Planner API. It will return a set of proposed routes which match the given input parameters.

The execution time of this method varies with the complexity of the route and other factors. Short routes should return with a couple of seconds whereas long routs with uncommon parameters can take tens of seconds the first time. Since planning is heavily using caching of distances and other information, subsequent method calls with similar parameters will usually be much faster.

The plan method accepts a large set of optional parameters. Since most of them are optional, you can leave out all parameters you have no real opinion on and a reasonable default will be chosen. The input parameters are:

KeyDatatype and UnitDescription
destinationsJSON arrayAn array of at least two destination objects (defined below). The first is the starting point, in-between are waypoints, and the last is the destination.
car_modelstring [typecode]The typecode (from the get_carmodels method) describing the exact car model to be used for the plan.
ref_consumptionfloat [Wh/km]The reference consumption of the car_model. The default reference consumption for each car model is given by the get_carmodels method. Unless there is better information, use this default.
fast_chargerscomma-separated stringA comma-separated list of charger types to be used in the route planning. The charger types are the same as in the get_chargers method.
initial_soc_percfloat [%][Optional] The starting SoC of the car.
charger_soc_percfloat [%][Optional] The minimum SoC allowed when arriving at any charger or waypoint.
arrival_soc_percfloat [%][Optional] The minimum SoC allowed when arriving at the final destination.
charge_overheadfloat [s][Optional] The overhead to add to the driving time and charging time for each charge stop. This typically accounts for finding the charger, connecting it and starting it. A higher value here will lead to fewer but longer charge stops.
speed_factor_percfloat [%][Optional] A speed factor relative to the speed limits or estimated speed of the road. Default is 100, and e.g. 110 means 10% faster than speed limits.
max_speedfloat [km/h][Optional] The maximum speed which the planner will allow for the car, even if speed limits allow more. This is mostly useful for very high speed highways, such as Autobahns.
allow_ferrystring ["true"/"false"][Optional] Allow the route to include ferries. Only one of "allow_ferry", "allow_toll" and "allow_motorway" can be disabled at a time.
allow_tollstring ["true"/"false"][Optional] Allow the route to include toll roads. Only one of "allow_ferry", "allow_toll" and "allow_motorway" can be disabled at a time.
allow_motorwaystring ["true"/"false"][Optional] Allow the route to include highways. Only one of "allow_ferry", "allow_toll" and "allow_motorway" can be disabled at a time.
adjust_speedstring ["true"/"false"][Optional] Allow the planner to lower the maximum speed for individual legs if this is needed to reach the next charger.
outside_tempfloat [degrees C][Optional] The outside temperature for the plan. This will affect consumption of the car model.
wind_speedfloat [m/s][Optional] The wind speed for the plan.
wind_dirstring ["head"/"tail"][Optional] The wind direction for the plan.
road_conditionstring ["normal", "rain", "heavy_rain"][Optional] This will increase the consumption according to a simple model of the road condition impact.
extra_weightfloat [kg][Optional] The extra weight assumed for the car for the plan. This will slightly increase the consumption (unless driving downhill).
battery_degradation_percfloat [%][Optional] The assumed battery degradation of the car compared to a brand new battery. Default is 5% for all cars.
path_stepsstring ["true"/"false"][Optional] If true (default) a detailed path step object will be included between any chargers or waypoints, including coordinates, SoC and elevation with high resolution along the way.
find_altsstring ["true"/"false"][Optional] If true, up to two alternative paths will be included in the plan. Default is false.
find_next_charger_altsstring ["true"/"false"][Optional] If true, up to five options for the next charger are returned (as different routes).
allowed_network_idscomma-separated string of network IDs[Optional] If given, this list of network IDs are the only allowed charger networks in the plan.
preferred_network_idscomma-separated string of network IDs[Optional] If given, this list of network IDs are will be preferred over other chargers. This is a soft decision, if other chargers are significantly better for the trip, they will still be used.
preferred_charge_cost_multiplierfloat[Optional] If given, the charge time of a preferred network charge is discounted by this factor. For example, 0.7 means that only 70% of the charging time is used as cost in the optimization. This does not affect the charging time presented to the user.
nonpreferred_charge_cost_additionfloat [s][Optional] If given, charging at a non-preferred network charge costs this many seconds extra. For example, a value of 600 means that charging at a non-preferred network charger is assumed to take 5 extra minutes (to make it less likely to be chosen). This does not affect the charging time presented to the user.
allowed_dbscomma-separated string of charger database providers[Optional] If given, one or more charger database providers can be specified, and only chargers from these database will be used in the planning.

A destination object is defined by:

KeyDatatype and UnitDescription
addressstringThe address of the destination. If not already known, it will be looked up by geocoding. Both street addresses and business names/POIs can be given.
This is optional if lat/lon or id is given.
latfloat[Optional] The latitude of the destination, if known.
lonfloat[Optional] The longitude of the destination, if known.
bearingfloat [degrees][Optional] The bearing of the vehicle at the waypoint, typically used for the starting point. The resulting plan will start within 30 degrees from this bearing. Useful when planning while driving.
idinteger[Optional] The charger id of the destination. This is typically an id retrieved using the get_chargers method.
charge_powerfloat [kW][Optional] For destination charging or overriding the charger default, this is the maximum charger power for charging at the destination. Can be negative to model vampire drain.
charge_timeinteger [s][Optional] For destination charging or overriding the planner optimized value, this is the time which the vehicle will be charging at this waypoint.
charge_to_percfloat [%][Optional] For destination charging or overriding the planner optimized value, this is the SoC which the vehicle will charge to at this waypoint.
arrive_percfloat [%][Optional] This can be used to override the global setting for waypoint arrival minimum SoC.

The result object of the plan method contains:

KeyDatatype and UnitDescription
routesArray [route]An array of routes, of which the first is the fastest found option. The others are alternative routes which are defined as being reasonably close in time to the best, and significantly different when it comes to route.
car_modelstring [typecode]The car model typecode for which the route was planned.
path_indicesObjectAn object defining the column numbering of the path array in the steps object. This is only to compact the size of the path array.

where each route object includes:

KeyDatatype and UnitDescription
stepsArray [step]Each step is a destination or charger plus the path between the present destination and the next one. The last step will therefore not contain a path.
total_drive_durationfloat [s]The total time spent driving the vehicle in this route.
total_charge_durationfloat [s]The total time spent charging the vehicle in this route.
total_distfloat [m]The total distance for this route.
average_consumptionfloat [Wh/km]The estimated average consumption for this route.

The step object id defined by:

KeyDatatype and UnitDescription
pathArray [path step arrays]This is the path between two steps in resolution about 200m steps or less. Each path step consists of an array (instead of an object, for compression) defined by the path_indices in the plan result. We will describe it as if each path step is an object.
If you do not need this information, you can disable the this field in the plan method by setting the parameter path_steps=false.
idintegerThe waypoint/charger id in the Iternio database. This can be used for planning destinations.
arrival_percfloat [%]The planned arrival SoC at this step (before any charging).
departure_percfloat [%]The planned departure SoC at this step (after any charging).
departure_durationfloat [s]The time left for the whole route when departing this step.
departure_distfloat [m]The distance left for the whole route when departing this step.
latfloatThe latitude of the waypoint/charger.
lonfloatThe longitude of the waypoint/charger.
utc_offsetinteger [s]The current offset from UTC for the local time zone at the waypoint/charger.
is_chargerbooleanTrue if this step is a charger.
is_waypointbooleanTrue if this step is a given input destination.
max_speedfloat [m/s]The planned maximum speed for path to the next step.
is_mod_speedbooleanIf the maximum speed has been reduced to reach the next step.

And finally, the path step object (which is encoded as an array for compression) is defined by:

KeyDatatype and UnitDescription
latfloatLatitude of the path step.
lonfloatLongitude of the pat step.
soc_percfloat [%]The remaining estimated SoC.
cons_per_kmfloat [Wh/km]The instantaneous estimated consumption.
speedfloat [m/s]The estimated speed of the vehicle.
remaining_timefloat [s]The remaining time for the whole route.
remaining_distfloat [s]The remaining distance for the whole route.
instructionstringAn English turn instruction.
speed_limitfloat [m/s]The present speed limit, if known.
elevationfloat [m]The elevation over mean sea level.
path_distancefloat [m]The distance for this path step only.

Example call:

https://api.iternio.com/1/plan?car_model=chevy%3Abolt%3A17%3A60%3Aother&api_key=<your API key>&ref_consumption=190&fast_chargers=ccs&destinations=%5B%7B%22lat%22%3A+49.343847%2C+%22lon%22%3A+2.078365%7D%2C+%7B%22address%22%3A+%22Amsterdam%22%7D%5D

That’s it! It is simpler than it looks.