1

TomTom Routing API

migration guide

(MapKit Routing -> Online Routing)

2

Purpose of This Document

This document is a field-by-field comparison of the request and response parameters

between the MapKit Routing and Online Routing APIs, with advice on how to move from one to the other. It should not be taken as full documentation of either API. That

can be found at: MapKit Map Toolkit Routing API v3

Online Routing API v1

Request

This table deals with routing calls as documented for the existing MapKit Routing API,

explaining what the equivalent parameters are in the Online Routing API. Where the Online Routing API does not fully implement the behaviors of the MapKit Routing API,

or where defaults are reversed, the differences are noted in bold to draw attention.

Note that there are other calls possible for the Online Routing engine, such as optimized routing, which have other parameter requirements. They are included for

information, but are not the focus of this chart.

MapKit Parameter Online Routing Equivalent

Convert from Convert to Other information

/points

/points Start point, end point, up to 3 intermediate

points in colon-delimited, comma-separated pairs

Expressed in

EPSG-4326 (lat/lon) (default) or

EPSG-900913

Start point, end point, up to 50 intermediate points in colon-

delimited, comma-separated pairs

Must be expressed in EPSG-4326 (lat/lon)

Optimized routing accepts up to 20 intermediate points

/routeType

[routeType=]

Quickest

Shortest

Green

AvoidMotor

way

Walk

Fastest

Shortest

Eco

Thrilling

You can choose the level of turns included and also

the degree of hilliness. See the hilliness and windingness parameters for how to set this.

Use the appropriate parameter from the

See below for more information about the Online Routing [avoid=] and [vehicleType=]

parameters.

3

Bicycle

SpeedLimite

d

above list, and add the following values:

avoid=motorways

travelMode=pedest

rian

Note that there is no

equivalent of the Bicycle and SpeedLimited route types.

/contentType

[/contentType=]

Mandatory parameter

Optional parameter, default is xml

The options for these two are the same in both interfaces

key key Authorization key

Authorization key Map Toolkit API keys will not work with

Online Maps. A new key must be issued.

[avoidTraffic=]

[traffic=]

Boolean parameter determining if traffic is to be taken into

account when determining the quickest route. Interacts with includeTraffic.

Default is false.

Boolean parameter determining if traffic is to be taken into account when calculating and describing routes.

Default is true.

See discussion of traffic parameters below.

[includeTraffic=]

[traffic=]

Boolean parameter

determining if traffic is to be taken into account when describing the route. Interacts

with avoidTraffic.

Default is false.

Boolean parameter determining if traffic is

to be taken into account when calculating and describing routes.

Default is true.

See discussion of traffic parameters below.

[language=] [language=] Used for creating guidance, default is en (ISO 639-1

code).

Used for creating guidance, default is en-GB (IETF language tags).

List of supported languages can be found in the documentation.

[day=]

[time=]

[departAt=] Day values are today (default), tomorrow, or the days of the week (lowercase).

now (default), which is the equivalent of the MapKit default of

today/now

RFC-3339 date and time format to indicate a time in a day of the

Note that the Online Routing parameter [departAt=] cannot be used in conjunction with [arriveAt=]. The

date and time

4

Times are now (default) or

minutes since midnight.

week

Note that tomorrow is not a valid input

cannot be in the past.

[iqRoutes=] Not relevant

Toggle IQ Routes:

(day-of

week)

(default)

off

(day-of-week) is

always enabled in

Online Routing

iqRoutes cannot be turned off

[trafficModelID=] Not relevant -1 (default)

to call the

latest traffic model ID.

a specific

traffic model ID (to synchronize with traffic

and traffic tile API calls)

Online Routing

always uses the

most recent traffic

No option to

select a specific traffic model

The default value of -1 in the MapKit

routing engine

should, in almost all cases, map to Online Routing behavior.

[avoidTolls=] [avoid=] default is false avoid=tollRoads is an optional parameter, so

the default is the same.

See below for more information about

the Online Routing avoid parameter

[includeInstructions=] [instructionsType=] default is true coded

text

tagged

When the

parameter is not filled, no guidance instructions are returned.

MapKit call provides

instructions by default.

instructionsType

parameter cannot be used in conjunction with routeRepresentation = none

[projection=] Not relevant EPSG4326 (lat/lon)

EPSG900913

Online Routing uses EPSG-4326

only

[pathPoints=] [routeRepresentation=] zoom levels 0..18

(default:

relative pathPoints)

:abs

polyline (no option to set

zoom level)

none (returns optimized waypoint order information

for route optimization)

Online Routing returns all points

The level of detail in the Online Routing routing engine polyline is

approximately the equivalent of a zoom level of 18.

5

in absolute format only

[jsonp=] [callback=]

(new in Online Routing)

[maxAlternatives=] The MapKit routing API only

provides a single route per routing call.

0 (default).. 5

This cannot be used in conjunction with

optimized routing.

(new in Online Routing)

[avoid=] The MapKit routing API has specific avoidance

functionality expressed in some of its

parameters (see above) rather than a single

"avoid" parameter.

tollRoads

motorways

ferries

unpavedRoads

carpools

(new in Online Routing)

[arriveAt=] The MapKit routing API has no option to set arrival time.

RFC-3339 date and time format to indicate a time in a day of the week

Cannot be used with [departAt=]. Time cannot be in the past.

(new in Online

Routing)

[computeBestOrder=] The MapKit

routing API does not offer waypoint optimization.

Boolean value

indicating whether the waypoint order should be optimized.

Can only be used

with specific combinations of parameters. Refer to the Online Routing API documentation for details on how to

use this function.

(new in Online Routing)

[travelMode=] The MapKit routing API uses the /routeType parameter to specify travel mode. See

above for how to use travelMode for this purpose.

car (default)

pedestrian

(new in Online Routing)

[report=] The MapKit routing API does not return

diagnostic

information of this type.

effectiveSettings

Diagnostic feature to help client developers. Refer to

the Online Routing

API documentation for details of how to use this parameter.

(new in Online Routing)

POSTed supporting points

Used to construct a route from detailed points (eg GPS tracks).

Refer to the Online

Routing API documentation for how to use this option.

6

(new in Online Routing)

[hilliness] The MapKit routing API has

no option to set level of hilliness

low

normal (default)

high

(new in Online Routing)

[windingness] The MapKit routing API has no option to set level of windingness

low

normal (default)

high

A note on traffic parameters

The MapKit routing engine uses three different parameters to determine what traffic affects planned routes and where that information is exposed:

iqRoutes

avoidTraffic includeTraffic

The iqRoutes parameter, and the associated day and time parameters, work as

follows in MapKit:

iqRoutes day/time Result Online Routing equivalent

false N/A Route optimizing algorithms use

maximum speed, modified by current traffic conditions

Not available: IQ Routes

information is always used by Online Routing.

true now/today Route optimizing algorithms use historic traffic speed for the current day and time, modified by current traffic conditions (see below)

departAt=now (default value, so optional)

true [current day of the week]/[current minutes after midnight]

As if now/today were entered departAt=[current time]

true [named day of the week]/[specified time] where

they are not equivalent to now/today

Route optimizing algorithms use historic traffic speed for the stated

day and time

departAt=[stated time]

When the user is departing at the current date and time, the avoidTraffic and includeTraffic parameters interact to produce specific effects:

7

avoidTraffic includeTraffic Result Online Routing equivalent

True True include current traffic incidents when

optimizing routes for speed

report delay time due to current traffic incidents in the instructions

traffic= true

True False do not include current traffic incidents when

optimizing routes for speed (this may be a bug)

do not report delay time due to current traffic incidents in the instructions

traffic= false

False True do not include current traffic incidents when

optimizing routes for speed

report delay time due to current traffic incidents in the instructions

There is no Online

Routing equivalent

False False do not include current traffic incidents when

optimizing routes for speed

do not report delay time due to current traffic incidents in the instructions

traffic= false

Response

Both MapKit and Online Routing support XML, JSON and JSONP responses. Below is a

comparison of the content of the responses from the two systems:

MapKit Response

Element

Online

Routing Equivalent

Conversion from Conversion

to

Other information

summary/routeKey Not relevant MapKit uses this to

enable the client to

obtain a map tile that

includes the rendered

route.

Online Routing

does not offer

tiles.

It is recommended

that the calling

applications use the

points in the

response to draw

their own route

lines.

summary/iqType Not relevant Reports the IQRoutes

algorithm used to

create the route.

iqRoutes cannot

be disabled in

Online Routing.

See the iqRoutes

parameter above

for more

information.

8

summary/bbox Not relevant A bounding box

containing the entire

route

defined by its

bottom left and top

right corners

stated in the

requested

projection

This

functionality is

not supported

by Online

Routing

MapKit bounding box

functionality is

intended to support

the display of map

tiles. The Online Routing

routing engine is not

intended to support

route display as well

as calculation.

Bounding box

information can be

calculated by the

calling application

based on the points

returned in the

response.

summary/trafficModelId Not relevant Reports the traffic

model used to

generate the route

Online Routing

does not offer

the option to

use a specific

traffic model;

it always uses

the most

recent traffic

data.

See the

trafficModelID

parameter above for

more information.

summary/startTimeZone route/summary

/departureTime The time zone of the

starting point

The departure

time contains

information

about the

timeZone of

the starting

point of the

route

summary/endTimeZone route/summary

/arrivalTime The time zone of the

end point The arrival

time contains

information

about the

timeZone of

the end point

of the route

summary/totalDelaySeconds

route/summary/trafficDelayInSeconds

The difference

between the travel

time, calculated using

all available traffic

information and travel

time at free flow

speeds.

The difference

between the

travel time

calculated

using

all available

traffic

information

and travel time

at free flow

speeds.

9

summary/totalDistance

Meters

summary/leng

thInMeters

summary/totalTimeSeco

nds

summary/travel

TimeInSeconds

summary/departureOve

rview

route/summary

/departureTime The departure day and

time (either now/today

or as specified in the

call), plus a message

to display in the

requested language.

The departure

day and time,

including time

zone of the

starting point

of the route.

summary/arrivalOvervie

w

route/summary

/arrivalTime The arrival day and

time, plus a message

to display in the

requested language.

The arrival day

and time,

including time

zone of the

end point of

the route.

summary/routeURI Not relevant This element is deprecated by

MapKit

instructions guidance/instructions

Information about each

section of the route,

delimited by navigation

points

Sets of

attributes

describing a

maneuver, e.g.

'Turn right',

'Keep left',

'Take the

ferry', 'Take

the motorway',

'Arrive'.(Note:

instructions

are present

only when

guidance was

requested and

is available).

Note: The segments

in MapKit

route/instructions do

not map Online

Routing legs.

MapKit instructions

describe the stage

of a journey ending

in a navigation

point (turn right,

bear left, etc.) The

navigation points

are determined by

the routing engine

itself.

Online Routing's

legs represent the

journey between

two sequential

waypoints as

entered in the

request.

10

pathPoints/ routes/legs/

points

Coordinates describing

the geometry of the

route in the

projection supplied in

the request. This is

expressed as

a list of latitudes, then a list of longitudes.

They must be matched by position in the list.

The detail represented by

the points is determined

by the zoom level in the

request.

Coordinates

describing the

geometry of

the route.

Online Routing

returns approximately

the same quantity of

coordinates as the

most detailed zoom

level of MapKit.

Unsupported optimizedWaypoints

MapKit does not

support waypoint

optimization.

Index values

for an

optimized

order of the

waypoints

entered in the

request.

Unsupported report/effectiv

eSettings MapKit does not

have this feature

The settings

used to

determine the

route (both

those explicitly

entered and

defaults

used)

Error Response “Invalid search center value: [52.3.724517662919,4.894409179687499]”

"Invalid route type: [faster]"

"Invalid avoid value: [Test]" “Engine error while executing route request: MAP_MATCHING_FAILURE"

“Engine error while executing route request: NO_ROUTE_FOUND"

11

How different MapKit Routing API calls can be transformed to

Online Routing API calls

MapKit

Routing

parameter

Online

Routing

equivalent

Convert from Convert to Other notes

/points /points Start point, end

point, up to 3

intermediate

points in colon-

delimited,

comma-separated

pairs.

Expressed in

EPSG-4326

(lat/lon) (default)

or EPSG-900913.

Start point, end point,

up to 50 intermediate

points in colon-

delimited, comma-

separated pairs. Must be expressed

in EPSG-4326

(lat/lon).

Online Routing: optimized

routing accepts up to 20 intermediate points

(with parameter computeBestOrder=true)

MapKit example:

https://api.tomtom.com/lbs/services/route/3/52.37,4.91:52.25,4.91:52.3,4.9/Quickest/xml?key=<

apiKey>

Online Routing examples:

https://api.tomtom.com/routing/1/calculateRoute/52.509317,13.429368:52.502746,13.438724/?

key=<apiKey> https://api.tomtom.com/routing/1/calculateRoute/52.509317,13.429368:52.502746,13.438724:5

2.509317,13.429368:52.502746,13.438724:52.50

9317,13.429368:52.502746,13.438724/?key=<apiKey>

MapKit Routing

parameter

Online Routing equivalent

Convert from Convert to

/routeType [routeType=] Quickest

Shortest

Green

AvoidMotorway

Walk

fastest (default)

shortest

eco

Additional parameters can be used with

parameters from list above:

avoid=motorways

travelMode=pedestrian

12

Example calls for MapKit and their equivalent calls for Online Routing:

MapKit examples:

https://api.tomtom.com/lbs/services/route/3/52.37,4.91:52.25,4.91:52.3,4.9/Quickest/xml?key=<a

piKey> https://api.tomtom.com/lbs/services/route/3/52.37,4.91:52.25,4.91:52.3,4.9/Shortest/xml?key=<a

piKey> https://api.tomtom.com/lbs/services/route/3/52.37,4.91:52.25,4.91:52.3,4.9/Green/xml?key=<apiK

ey>

Online Routing equivalents, respectively:

https://api.tomtom.com/routing/1/calculateRoute/52.509317,13.429368:52.502746,13.438

724/?key=<apiKey>&routeType=fastest

https://api.tomtom.com/routing/1/calculateRoute/52.509317,13.429368:52.502746,13.438

724/?key=<apiKey>&routeType=shortest

https://api.tomtom.com/routing/1/calculateRoute/52.509317,13.429368:52.502746,13.438

724/?key=<apiKey>&routeType=eco

Example while avoiding motorways. MapKit example:

https://api.tomtom.com/lbs/services/route/3/52.37,4.91:52.25,4.91:52.3,4.9/AvoidMotorway/xml?k

ey=<apiKey>

Online Routing equivalent:

https://api.tomtom.com/routing/1/calculateRoute/52.509317,13.429368:52.502746,13.438724/?key

=<apiKey>&avoid=motorways

Example for pedestrians. MapKit example:

https://api.tomtom.com/lbs/services/route/3/52.37,4.91:52.25,4.91:52.3,4.9/Walk/xml?key=<apiKey>

Online Routing example:

https://api.tomtom.com/routing/1/calculateRoute/52.509317,13.429368:52.502746,13.438724/?key

=<apiKey>&travelMode=pedestrian

Note that in Online Routing, parameters: routeType, avoid and travelMode can be used in single Online Routing call:

https://api.tomtom.com/routing/1/calculateRoute/52.509317,13.429368:52.502746,13.438724/?key

=<apiKey>&travelMode=pedestrian&avoid=motorways&routeType=fastest

13

MapKit Routing

parameter

Online

Routing

parameter

Convert from Convert to

[avoidTraffic=] [traffic=] Boolean parameter determining if traffic is to be

taken into account when determining

the quickest route. Interacts with

includeTraffic.

Default is false.

Boolean parameter determining if

traffic is to be taken into account

when calculating and

describing routes. Default is true.

[includeTraffic=] [traffic=] Boolean parameter determining if

traffic is to be taken into account when

describing the route.

Interacts with avoidTraffic. Default is false.

Boolean parameter determining if

traffic is to be taken into account

when calculating and

describing routes. Default is true.

When parameter avoidTraffic in MapKit is set to true, traffic will be considered

while planning route, and when parameter includeTraffic is set to true, traffic

delay time will be included route summary.

MapKit example:

https://api.tomtom.com/lbs/services/route/3/52.37,4.91:52.25,4.91:52.3,4.9/Quickest/xml?avoidTra

ffic=true&includeTraffic=true&key=<apiKey>

Online Routing equivalent (when traffic is true, this means to consider traffic and traffic delay when planning route):

https://api.tomtom.com/routing/1/calculateRoute/52.509317,13.429368:52.502746,13.438724/?traff

ic=true&key=<apiKey>

14

MapKit

Routing

parameter

Online

Routing

parameter

Convert from Convert to Other notes

[day=]

[time=]

[departAt=] Day values are

today (default), tomorrow , or

the days of the

week

(lowercase). Times are now

(default) or

minutes since

midnight.

now (default),

which is the

equivalent of the

MapKit default of

today/now

RFC-3339 date

and time

format to

indicate a time

in a day of the

week

Note that tomorrow is

not a valid input

Note that the

Online Routing parameter [departAt=] cannot be used in conjunction with [arriveAt=]. The

date and time cannot be in the past.

Example when day and time are now:

MapKit example:

https://api.tomtom.com/lbs/services/route/3/52.37,4.91:52.25,4.91:52.3,4.9/Quickest/xml?day=tod

ay&time=now&key=<apiKey>

Online Routing equivalent:

https://api.tomtom.com/routing/1/calculateRoute/52.509317,13.429368:52.502746,13.438724/?dep

artAt=now&key=<apiKey>

Example when day and time are chosen day in the week:

MapKit example (only day of the week and amount of minutes from local midnight

can be chosen):

https://api.tomtom.com/lbs/services/route/3/52.37,4.91:52.25,4.91:52.3,4.9/Quickest/xml?day=mo

nday&time=360&key=<apiKey>

Online Routing equivalent (correct date must be specified, note: chosen date must be in the future):

https://api.tomtom.com/routing/1/calculateRoute/52.509317,13.429368:52.502746,13.438724/?dep

artAt=2015-11-14T16%3A39%3A57-08%3A0

0&key=<apiKey>

15

MapKit Routing

parameter

Online Routing

parameter

Convert

from

Convert to

[avoidTolls=] [avoid=] default is

false avoid=tollRoads is an

optional parameter, so the default is the same.

MapKit example when avoiding tolls:

https://api.tomtom.com/lbs/services/route/3/52.37,4.91:52.25,4.91:52.3,4.9/Quickest/xml?avoidTol

ls=true&key=<apiKey> Online Routing equivalent (you can choose only one element to avoid e.g.

motorways, tollRoads):

https://api.tomtom.com/routing/1/calculateRoute/52.509317,13.429368:52.502746,13.438724/?avoi

d=tollRoads&key=<apiKey>

MapKit

Routing

parameter

Online

Routing

parameter

Convert

from

Convert

to

Other notes

[includeInstruct

ions=]

[instructionsTy

pe=] default is

true coded

text

tagged

MapKit call provides instructions by default.

instructionsType parameter cannot be used

in conjunction with routeRepresentation =

none .

In MapKit only turn-by-turn instructions can be chosen. Example:

https://api.tomtom.com/lbs/services/route/3/52.37,4.91:52.25,4.91:52.3,4.9/Quickest/xml?includeI

nstructions=true&key=<apiKey>

In Online Routing one from three different types of instructions can be chosen:

https://api.tomtom.com/routing/1/calculateRoute/52.509317,13.429368:52.502746,13.438724/?inst

ructionsType=coded&key=<apiKey>

https://api.tomtom.com/routing/1/calculateRoute/52.509317,13.429368:52.502746,13.438724/?inst

ructionsType=text&key=<apiKey>

https://api.tomtom.com/routing/1/calculateRoute/52.509317,13.429368:52.502746,13.438724/?inst

ructionsType=tagged&key=<apiKey>

16

MapKit

Routing

parameter

Online

Routing

parameter

Convert

from

Convert to Other notes

[pathPoints

=]

[routeReprese

ntation=] zoom

levels

0..18

(default:

relative

pathPoin

ts) :abs

polyline (no option to set

zoom level)

none (returns optimized

waypoint order

information for route

optimization)

Online Routing returns

all points in absolute

format only

The level of detail in the

Online Routing routing

engine

polyline is approximately

the equivalent of a zoom

level of 18.

MapKit example:

https://api.tomtom.com/lbs/services/route/3/52.37,4.91:52.25,4.91:52.3,4.9/Quickest/xml?pathPoin

ts=18:abs&key=<apiKey>

Other MapKit zoom levels and option where first coordinate pair will be absolute

(with :abs after zoom level), and succeeding ones will be encoded as deltas

does not have equivalents in Online Routing.

Online Routing equivalent:

https://api.tomtom.com/routing/1/calculateRoute/52.509317,13.429368:52.502746,13.438724/?rout

eRepresentation=polyline&key=<apiKey>

MapKit Routing

parameter

Online Routing

parameter

Convert

from

Convert

to

Other notes

[jsonp=] [callback=] Only used when contentType is

jsonp.

This is a parameter where json callback method name can be specified. Only name of this parameter was changed.

There are also other parameters in Online Routing you can use. If you want

more information, refer to Online Routing documentation. Note: Map Kit API keys will not work with Online Routing. A new API key for

Online Routing must be issued.

17

Which MapKit API calls do not have an equivalent in Online

Routing

MapKit Routing parameter

Online Routing equivalent

Convert from Convert to

/routeType [routeType=] (among other

parameters):

Bicycle

SpeedLimited

There is no equivalent of Bicycle and

SpeedLimited parameters

Not available:

https://api.tomtom.com/lbs/services/route/3/52.25238,4.89859:52.37017,4.93247/Bicycle/xml?key

=<apiKey> https://api.tomtom.com/lbs/services/route/3/52.25238,4.89859:52.37017,4.93247/SpeedLimited/x

ml?key=<apiKey>

MapKit Routing

parameter

Online Routing

equivalent

Convert from Convert to

[day=]

[time=]

[departAt=] (among other

parameters): tomorrow

There is no option so set the date as tomorrow.

There are only 2 possibilities: now (which means RFC-3339 date & time)

RFC-3339 date & time

Not available:

https://api.tomtom.com/lbs/services/route/3/52.25238,4.89859:52.37017,4.93247/Quickest/xml?key

=<apiKey>&day=tomorrow&time=43

MapKit Routing parameter

Online Routing equivalent

Convert from Convert to

[iqRoutes=] not relevant Toggle IQ Routes: (day-of

week)

(default)

off

(day-of-week) is always

enabled in Online Routing

iqRoutes cannot be turned

off

Not available:

https://api.tomtom.com/lbs/services/route/3/52.25238,4.89859:52.37017,4.93247/Quickest/xml?key

=<apiKey>&iqRoutes=0

18

MapKit

Routing

parameter

Online

Routing

equivalent

Convert from Convert to

[trafficModelID=] not

relevant

-1 (default) to call the latest traffic

model ID.

a specific traffic model ID (to

synchronize with traffic and traffic

tile API calls)

Online Routing

always uses the

most recent traffic

No option to select

a specific traffic

model

Not available:

https://api.tomtom.com/lbs/services/route/3/52.25238,4.89859:52.37017,4.93247/Quickest/xml?key

=<apiKey>&trafficModelID=10

MapKit Routing

parameter

Online Routing

equivalent

Convert from Convert to

[projection=] not relevant EPSG4326 (lat/lon)

EPSG900913

Online Routing uses EPSG-

4326 only

Not available:

https://api.tomtom.com/lbs/services/route/3/6790043.579195,511655.515558:6859219.08979

3,631967.398079/Quickest/xml?key=<apiKey>&projection=EPSG900913

MapKit Routing

parameter

Online Routing

equivalent

Convert from Convert to

[pathPoints=] [routeRepresentation=] zoom levels

0..18

(default:

relative

pathPoints) :abs

polyline (no option to set

zoom level)

none (returns optimized

waypoint order information for

route optimization)

Online Routing returns all

points in absolute format

only

Not available:

https://api.tomtom.com/lbs/services/route/3/52.25238,4.89859:52.37017,4.93247/Quickest/xml?key

=<apiKey>&iqRoutes=0&pathPoints=10