Developer

Migrate from Google to TomTom

Service version: 3
Last edit: 2026.07.07
TomTom Orbis Maps

Overview

This guide is for developers currently using Google's Routes API (computeRoutes) who want to evaluate or switch to TomTom's Orbis Routing API v3 (routes/calculate). It's split into four parts:

  • Response structure at a glance — how the overall shape of a response differs, in rough terms, before getting into individual fields.
  • Common use cases — a walkthrough of guide topics Google covers at developers.google.com/maps/documentation/routes, each with how the same thing is done on TomTom.
  • Input — Google request headers/fields, with their TomTom equivalent.
  • Output — Google response fields, with their TomTom equivalent.

Prerequisites

Response structure at a glance

Before comparing individual fields, it helps to see how the two response shapes differ overall.

Both wrap results in a top-level routes[] array, and both give each route its own legs[] array. Past that point, the two structures diverge:

  • Route-level facts. Google puts distance, duration, and geometry directly on the route object (distanceMeters, duration, polyline). TomTom groups the equivalent facts into a single summary object (lengthInMeters, travelDurationInSeconds, trafficDelayDurationInSeconds), and returns geometry as GeoJSON in the path field — no decoding step needed before rendering, unlike Google's compressed polyline.encodedPolyline string.
  • Turn-by-turn detail. Google nests navigation instructions inside each leg's steps[] array — one step per maneuver, in route order. TomTom instead returns a single flat instructions[] array at the route level, independent of the legs[] array, and only when guidance is requested (see Get turn-by-turn navigation instructions).
  • Segment/incident detail. Google attaches this kind of information contextually — for example travelAdvisory.speedReadingIntervals[] for traffic, travelAdvisory.tollInfo for tolls. TomTom collects all of it into one sections object: a map keyed by segment type (traffic, toll, tunnel, motorway, and others), where each entry is an array of path-index ranges describing where that segment type applies along the route.
  • Legs. Both APIs have a legs[] array marking where the route splits at each waypoint. On TomTom, each leg carries its own summary and path, mirroring the route-level structure at a smaller scope.

In short: Google's response reads top-down through legs[] → steps[], with detail embedded at each level. TomTom's response reads more like a route-level summary plus a handful of parallel arrays (legs[], instructions[], sections) that you cross-reference by path index.

Common use cases

This section walks through the guide topics Google groups its own Routes API docs into, in the same order, and shows how the same thing is done on TomTom. Values in the examples are illustrative.

Get a route

The baseline for any routing integration — everything else in this guide builds on it. routePlanningLocations.origin and routePlanningLocations.destination are the only required fields, along with the Attributes and TomTom-Api-Version headers (see Input); routeType and traffic determine which route is returned.

Google

post
POST request curl command example
1curl -X POST "https://routes.googleapis.com/directions/v2:computeRoutes" -H "X-Goog-Api-Key: YOUR_API_KEY" -H "X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline" -H "Content-Type: application/json" -d \
2'{
3  "origin": {
4    "location": {
5      "latLng": {
6        "latitude": 52.50931,
7        "longitude": 13.42936
8      }
9    }
10  },
11  "destination": {
12    "location": {
13      "latLng": {
14        "latitude": 52.50274,
15        "longitude": 13.43872
16      }
17    }
18  },
19  "travelMode": "DRIVE",
20  "routingPreference": "TRAFFIC_AWARE"
21}'

Response:

1{
2  "routes": [
3    {
4      "distanceMeters": 1147,
5      "duration": "180s",
6      "polyline": {
7        "encodedPolyline": "ipkcFfindQ_yZg}Bpxdd@"
8      }
9    }
10  ]
11}

TomTom

post
POST request curl command example
1curl -X POST "https://api.tomtom.com/maps/orbis/routing/routes/calculate" -H "Content-Type:application/json" -H "TomTom-Api-Version:3" -H "TomTom-Api-Key:{Your_API_Key}" -H "Attributes:routes" -d \
2'{
3  "routePlanningLocations": {
4    "origin": {
5      "type": "Point",
6      "coordinates": [13.42936, 52.50931]
7    },
8    "destination": {
9      "type": "Point",
10      "coordinates": [13.43872, 52.50274]
11    }
12  },
13  "routeType": "fast",
14  "traffic": "live"
15}'

Response:

1{
2  "routes": [
3    {
4      "summary": {
5        "lengthInMeters": 1147,
6        "travelDurationInSeconds": 180,
7        "trafficDelayDurationInSeconds": 15
8      },
9      "path": {
10        "type": "LineString",
11        "coordinates": [[13.42936, 52.5093], [13.42859, 52.50844]]
12      }
13    }
14  ]
15}

Choose a route type

Useful when the default fastest route isn't what your app needs — for example prioritizing fuel efficiency, or minimizing distance instead of travel time. Both APIs use a single parameter with different values for this: Google's requestedReferenceRoutes (FUEL_EFFICIENT, SHORTER_DISTANCE) and TomTom's routeType (efficient, short) used above — the request shape is the same on both sides.

What differs is the response:

Google returns the requested route type alongside the regular default route in the same routes[] array, distinguished by the routeLabels field (DEFAULT_ROUTE, FUEL_EFFICIENT, SHORTER_DISTANCE).
TomTom returns only a route of the requested type — there is no separate default route in the response.

  • Eco-friendly — Google: requestedReferenceRoutes: ["FUEL_EFFICIENT"] plus routeModifiers.vehicleInfo.emissionType. TomTom: routeType: "efficient"
  • Shorter distance — Google: requestedReferenceRoutes: ["SHORTER_DISTANCE"]. TomTom: routeType: "short". For long-distance planning prefer fast — see the routeType parameter in Calculate Route for details.

Google

post
POST request curl command example
1curl -X POST "https://routes.googleapis.com/directions/v2:computeRoutes" -H "X-Goog-Api-Key: YOUR_API_KEY" -H "X-Goog-FieldMask: routes.distanceMeters,routes.duration,routes.routeLabels" -H "Content-Type: application/json" -d \
2'{
3  "origin": {
4    "location": {
5      "latLng": {
6        "latitude": 52.50931,
7        "longitude": 13.42936
8      }
9    }
10  },
11  "destination": {
12    "location": {
13      "latLng": {
14        "latitude": 52.50274,
15        "longitude": 13.43872
16      }
17    }
18  },
19  "travelMode": "DRIVE",
20  "requestedReferenceRoutes": ["FUEL_EFFICIENT"],
21  "routeModifiers": {
22    "vehicleInfo": {
23      "emissionType": "ELECTRIC"
24    }
25  }
26}'

Response (abridged) — two routes come back, distinguished by routeLabels:

1{
2  "routes": [
3    {
4      "routeLabels": ["DEFAULT_ROUTE"],
5      "distanceMeters": 1147,
6      "duration": "180s"
7    },
8    {
9      "routeLabels": ["FUEL_EFFICIENT"],
10      "distanceMeters": 1201,
11      "duration": "210s"
12    }
13  ]
14}

TomTom

post
POST request curl command example
1curl -X POST "https://api.tomtom.com/maps/orbis/routing/routes/calculate" -H "Content-Type:application/json" -H "TomTom-Api-Version:3" -H "TomTom-Api-Key:{Your_API_Key}" -H "Attributes:routes" -d \
2'{
3  "routePlanningLocations": {
4    "origin": {
5      "type": "Point",
6      "coordinates": [13.42936, 52.50931]
7    },
8    "destination": {
9      "type": "Point",
10      "coordinates": [13.43872, 52.50274]
11    }
12  },
13  "routeType": "efficient",
14  "vehicleEngineType": "electric"
15}'

Get turn-by-turn navigation instructions

Use this when your app needs to display or speak step-by-step directions to the driver. Setting guidance to instructions (with instructionPhonetics) is what populates the instructions[] array in the response.

Google

post
POST request curl command example
1curl -X POST "https://routes.googleapis.com/directions/v2:computeRoutes" -H "X-Goog-Api-Key: YOUR_API_KEY" -H "X-Goog-FieldMask: routes.legs.steps.navigationInstruction,routes.legs.steps.distanceMeters" -H "Content-Type: application/json" -d \
2'{
3  "origin": {
4    "location": {
5      "latLng": {
6        "latitude": 52.50931,
7        "longitude": 13.42936
8      }
9    }
10  },
11  "destination": {
12    "location": {
13      "latLng": {
14        "latitude": 52.50274,
15        "longitude": 13.43872
16      }
17    }
18  },
19  "travelMode": "DRIVE"
20}'

Response:

1{
2  "routes": [
3    {
4      "legs": [
5        {
6          "steps": [
7            {
8              "distanceMeters": 200,
9              "navigationInstruction": {
10                "maneuver": "TURN_RIGHT",
11                "instructions": "Turn right onto Main Street"
12              }
13            }
14          ]
15        }
16      ]
17    }
18  ]
19}

TomTom

post
POST request curl command example
1curl -X POST "https://api.tomtom.com/maps/orbis/routing/routes/calculate" -H "Content-Type:application/json" -H "TomTom-Api-Version:3" -H "TomTom-Api-Key:{Your_API_Key}" -H "Attributes:routes" -d \
2'{
3  "routePlanningLocations": {
4    "origin": {
5      "type": "Point",
6      "coordinates": [13.42936, 52.50931]
7    },
8    "destination": {
9      "type": "Point",
10      "coordinates": [13.43872, 52.50274]
11    }
12  },
13  "guidance": "instructions",
14  "instructionPhonetics": "ipa"
15}'

Response (abridged):

1{
2  "routes": [
3    {
4      "instructions": [
5        {
6          "maneuverPoint": {
7            "latitude": 52.50603,
8            "longitude": 13.43404
9          },
10          "maneuver": "turnRight",
11          "message": "Turn right onto Skalitzer Straße."
12        }
13      ]
14    }
15  ]
16}

Get alternative routes

Useful when you want to let the user pick between multiple route options instead of only the single best one. Set maxPathAlternativeRoutes to the number of extra route options you want back (up to 5). Google returns up to three alternatives alongside the default route, and returns no alternatives at all when the request also has intermediate waypoints (the request itself isn't rejected — computeAlternativeRoutes is simply ignored in that case). TomTom has no such restriction, so alternatives and waypoints can be combined freely.

Google

post
POST request curl command example
1curl -X POST "https://routes.googleapis.com/directions/v2:computeRoutes" -H "X-Goog-Api-Key: YOUR_API_KEY" -H "X-Goog-FieldMask: routes.distanceMeters,routes.duration" -H "Content-Type: application/json" -d \
2'{
3  "origin": {
4    "location": {
5      "latLng": {
6        "latitude": 52.50931,
7        "longitude": 13.42936
8      }
9    }
10  },
11  "destination": {
12    "location": {
13      "latLng": {
14        "latitude": 52.50274,
15        "longitude": 13.43872
16      }
17    }
18  },
19  "travelMode": "DRIVE",
20  "computeAlternativeRoutes": true
21}'

TomTom

post
POST request curl command example
1curl -X POST "https://api.tomtom.com/maps/orbis/routing/routes/calculate" -H "Content-Type:application/json" -H "TomTom-Api-Version:3" -H "TomTom-Api-Key:{Your_API_Key}" -H "Attributes:routes" -d \
2'{
3  "routePlanningLocations": {
4    "origin": {
5      "type": "Point",
6      "coordinates": [13.42936, 52.50931]
7    },
8    "destination": {
9      "type": "Point",
10      "coordinates": [13.43872, 52.50274]
11    }
12  },
13  "maxPathAlternativeRoutes": 2
14}'

Specify waypoints

Useful for multi-stop trips, such as a delivery run or a road trip with planned stops along the way. List the stops in routePlanningLocations.waypoints, in the order they should be visited.

Google

post
POST request curl command example
1curl -X POST "https://routes.googleapis.com/directions/v2:computeRoutes" -H "X-Goog-Api-Key: YOUR_API_KEY" -H "X-Goog-FieldMask: routes.distanceMeters,routes.duration" -H "Content-Type: application/json" -d \
2'{
3  "origin": {
4    "location": {
5      "latLng": {
6        "latitude": 52.50931,
7        "longitude": 13.42936
8      }
9    }
10  },
11  "intermediates": [
12    {
13      "location": {
14        "latLng": {
15          "latitude": 52.51,
16          "longitude": 13.4
17        }
18      }
19    }
20  ],
21  "destination": {
22    "location": {
23      "latLng": {
24        "latitude": 52.50274,
25        "longitude": 13.43872
26      }
27    }
28  },
29  "travelMode": "DRIVE"
30}'

TomTom

post
POST request curl command example
1curl -X POST "https://api.tomtom.com/maps/orbis/routing/routes/calculate" -H "Content-Type:application/json" -H "TomTom-Api-Version:3" -H "TomTom-Api-Key:{Your_API_Key}" -H "Attributes:routes" -d \
2'{
3  "routePlanningLocations": {
4    "origin": {
5      "type": "Point",
6      "coordinates": [13.42936, 52.50931]
7    },
8    "waypoints": {
9      "type": "MultiPoint",
10      "coordinates": [[13.4, 52.51]]
11    },
12    "destination": {
13      "type": "Point",
14      "coordinates": [13.43872, 52.50274]
15    }
16  }
17}'

Specify vehicle heading and side of road

Useful for improving pickup/drop-off accuracy, for example in ride-hailing or delivery apps where the vehicle shouldn't have to cross traffic to reach a stop. vehicleHeadingInDegrees biases the initial direction of travel, and arrivalSidePreference controls which side of the street a stop is approached from.

Google

post
POST request curl command example
1curl -X POST "https://routes.googleapis.com/directions/v2:computeRoutes" -H "X-Goog-Api-Key: YOUR_API_KEY" -H "X-Goog-FieldMask: routes.distanceMeters,routes.duration" -H "Content-Type: application/json" -d \
2'{
3  "origin": {
4    "location": {
5      "latLng": {
6        "latitude": 52.50931,
7        "longitude": 13.42936
8      },
9      "heading": 90
10    }
11  },
12  "destination": {
13    "location": {
14      "latLng": {
15        "latitude": 52.50274,
16        "longitude": 13.43872
17      }
18    },
19    "sideOfRoad": true
20  },
21  "travelMode": "DRIVE"
22}'

TomTom

post
POST request curl command example
1curl -X POST "https://api.tomtom.com/maps/orbis/routing/routes/calculate" -H "Content-Type:application/json" -H "TomTom-Api-Version:3" -H "TomTom-Api-Key:{Your_API_Key}" -H "Attributes:routes" -d \
2'{
3  "routePlanningLocations": {
4    "origin": {
5      "type": "Point",
6      "coordinates": [13.42936, 52.50931]
7    },
8    "destination": {
9      "type": "Point",
10      "coordinates": [13.43872, 52.50274]
11    }
12  },
13  "vehicleHeadingInDegrees": 90,
14  "arrivalSidePreference": "curbSide"
15}'

Specify how and if to include traffic data

Useful for giving users an accurate ETA that reflects current conditions or a planned future departure. traffic chooses between live and historical data, and departureDateTime/arrivalDateTime set when the trip starts or ends — see Input for the timestamp format differences. On Google, traffic-aware routing (routingPreference) only applies to DRIVE and TWO_WHEELER.

Google

post
POST request curl command example
1curl -X POST "https://routes.googleapis.com/directions/v2:computeRoutes" -H "X-Goog-Api-Key: YOUR_API_KEY" -H "X-Goog-FieldMask: routes.distanceMeters,routes.duration" -H "Content-Type: application/json" -d \
2'{
3  "origin": {
4    "location": {
5      "latLng": {
6        "latitude": 52.50931,
7        "longitude": 13.42936
8      }
9    }
10  },
11  "destination": {
12    "location": {
13      "latLng": {
14        "latitude": 52.50274,
15        "longitude": 13.43872
16      }
17    }
18  },
19  "travelMode": "DRIVE",
20  "routingPreference": "TRAFFIC_AWARE_OPTIMAL",
21  "departureTime": "2027-07-10T15:01:23Z"
22}'

TomTom

post
POST request curl command example
1curl -X POST "https://api.tomtom.com/maps/orbis/routing/routes/calculate" -H "Content-Type:application/json" -H "TomTom-Api-Version:3" -H "TomTom-Api-Key:{Your_API_Key}" -H "Attributes:routes" -d \
2'{
3  "routePlanningLocations": {
4    "origin": {
5      "type": "Point",
6      "coordinates": [13.42936, 52.50931]
7    },
8    "destination": {
9      "type": "Point",
10      "coordinates": [13.43872, 52.50274]
11    }
12  },
13  "traffic": "live",
14  "departureDateTime": "2027-07-10T15:01:23"
15}'

Specify route features to avoid

Useful for vehicles or drivers that can't or don't want to use certain road types, such as trucks avoiding tunnels or drivers avoiding tolls. List the road types to steer away from in the avoids array.

Google

post
POST request curl command example
1curl -X POST "https://routes.googleapis.com/directions/v2:computeRoutes" -H "X-Goog-Api-Key: YOUR_API_KEY" -H "X-Goog-FieldMask: routes.distanceMeters,routes.duration" -H "Content-Type: application/json" -d \
2'{
3  "origin": {
4    "location": {
5      "latLng": {
6        "latitude": 52.50931,
7        "longitude": 13.42936
8      }
9    }
10  },
11  "destination": {
12    "location": {
13      "latLng": {
14        "latitude": 52.50274,
15        "longitude": 13.43872
16      }
17    }
18  },
19  "travelMode": "DRIVE",
20  "routeModifiers": {
21    "avoidTolls": true,
22    "avoidHighways": true,
23    "avoidFerries": true
24  }
25}'

TomTom

post
POST request curl command example
1curl -X POST "https://api.tomtom.com/maps/orbis/routing/routes/calculate" -H "Content-Type:application/json" -H "TomTom-Api-Version:3" -H "TomTom-Api-Key:{Your_API_Key}" -H "Attributes:routes" -d \
2'{
3  "routePlanningLocations": {
4    "origin": {
5      "type": "Point",
6      "coordinates": [13.42936, 52.50931]
7    },
8    "destination": {
9      "type": "Point",
10      "coordinates": [13.43872, 52.50274]
11    }
12  },
13  "avoids": ["tollRoads", "motorways", "ferries"]
14}'

TomTom's avoids array also supports unpavedRoads, carpools, borderCrossings, tunnels, carTrains, and alreadyUsedRoads, which have no Google equivalent.

Input: Google request fields and their TomTom equivalent

Headers

Google Routes APITomTom Orbis Routing API v3What it does
X-Goog-Api-KeyTomTom-Api-KeyAuthenticates the request.
(implicit in endpoint)TomTom-Api-Version header or apiVersion query parameter (one of the two required)Selects which API version handles the request.
X-Goog-FieldMask (required)Attributes header (required) + optional Attributes-Exclude headerSelects which fields are included in the response.

Request body

Google Routes API fieldTomTom Orbis Routing API v3 equivalentWhat it does
origin (waypoint object)routePlanningLocations.origin (GeoJSON Point)Where the route starts.
destination (waypoint object)routePlanningLocations.destination (GeoJSON Point)Where the route ends.
intermediates[] (up to 25)routePlanningLocations.waypoints (GeoJSON MultiPoint, up to 150)Stops the route must pass through, in order.
Waypoint.location.latLngGeoJSON Point coordinatesThe coordinate pair for a location — GeoJSON orders it [longitude, latitude], the reverse of Google's latLng.
Waypoint.location.heading (per-waypoint)vehicleHeadingInDegrees (route-level)Biases the initial direction of travel.
Waypoint.sideOfRoad (boolean)arrivalSidePreference: anySide, curbSideControls which side of the street a stop is approached from.
travelMode: DRIVEtravelMode: carTomTom's Calculate Route currently supports only car.
routingPreference: TRAFFIC_AWARE, TRAFFIC_AWARE_OPTIMAL (DRIVE/TWO_WHEELER only)traffic: liveUses real-time traffic conditions when calculating the route.
routingPreference: TRAFFIC_UNAWAREtraffic: historicalUses historical average speeds instead of live conditions.
requestedReferenceRoutes: FUEL_EFFICIENT (returned alongside the default route)routeType: efficient (returned instead of the default route)Optimizes for fuel or energy efficiency instead of speed.
requestedReferenceRoutes: SHORTER_DISTANCE (returned alongside the default route)routeType: short (returned instead of the default route)Optimizes for the shortest distance instead of speed.
(default/fastest route)routeType: fastOptimizes for the fastest travel time.
computeAlternativeRoutes (boolean, up to 3 alternatives in addition to the default route, ignored when intermediates is set)maxPathAlternativeRoutes (integer, up to 5 alternatives in addition to the primary route)Requests additional routes besides the primary one.
routeModifiers.avoidTolls (DRIVE/TWO_WHEELER only)avoids: tollRoadsAvoids toll roads.
routeModifiers.avoidHighways (DRIVE/TWO_WHEELER only)avoids: motorwaysAvoids motorways/highways.
routeModifiers.avoidFerries (DRIVE/TWO_WHEELER only)avoids: ferriesAvoids ferries.
routeModifiers.vehicleInfo.emissionTypevehicleEngineType: combustion, electricThe vehicle's power source, used when computing eco-friendly (efficient) routes.
languageCodeAccept-Language headerSets the language used for street names and instructions.
departureTime (RFC 3339, offset required; mutually exclusive with arrivalTime)departureDateTime (RFC 3339, offset optional; mutually exclusive with arrivalDateTime)When the trip should start.
arrivalTime (RFC 3339, offset required; TRANSIT mode only)arrivalDateTime (RFC 3339, offset optional)When the trip should end.
polylineEncoding: GEO_JSON_LINESTRINGpath (returned by default)The format used to represent the route geometry.

Output: Google response fields and their TomTom equivalent

Response body

Google Routes API fieldTomTom Orbis Routing API v3 equivalentWhat it does
distanceMeterssummary.lengthInMetersTotal route distance.
duration (string, e.g. "500s")summary.travelDurationInSeconds (number)Total estimated travel duration.
polyline.geoJsonLinestringpathThe route geometry as a line.
legs[] (distanceMeters, duration, staticDuration, startLocation, endLocation)legs[] (each with its own summary and path)Splits the route into segments at each waypoint.
legs[].steps[].navigationInstructioninstructions[] (opt-in via guidance, see Input)Turn-by-turn guidance for the driver.
navigationInstruction.instructions (free text)instructions[].messageThe human-readable instruction text.
navigationInstruction.maneuver (enum)instructions[].maneuver (enum)The type of maneuver to perform (e.g. turn left).
travelAdvisory.speedReadingIntervals[]sections.traffic[] (iconCategory, delayMagnitude, effectiveSpeedInKilometersPerHour, delayDurationInSeconds)Traffic conditions along the route.

Further reading