Sorry, you need to enable JavaScript to visit this website.

Online Routing


This endpoint will return route information. We based the options for this end point on the same JSON configuration options that are present in our JavaScript API. The Online Routing (legacy) engine provides a huge number of tunable options for generating the optimal route. 

To send the criteria you will still use a GET request with the JSON as a string value for the criteria parameter, e.g.: 

GET

?criteria={"distanceUnit":"FT","routePreference":"Pedestrian", ... }

Request

Format

Route between two points:

GET https://<baseURL>/routing/<versionNumber>/route/<from>/<to>.<ext>?key=<apiKey>[&criteria=<criteria>]

The table below describes all of the parameters that can be used in a request. Required parameters must be used or the call will fail. Optional parameters, which are highlighted with [square brackets], may be used. If there is a default value that will be assumed when an optional parameter is not used, it is shown in the table. The order of request parameters is not important.

Parameter Description Req'd? Type / Values Default Value Max Value
baseURL
Base URL for calling the API. Yes api.tomtom.com
versionNumber
Service version number. The current value is 0. Yes 0
from
This is specified as a comma separated string composed by lat., lon. (e.g.: 37.337,-121.89). Yes Position
to
This is specified as a comma separated string composed by lat., lon. (e.g.: 37.337,-121.89). Yes Position
ext 
Valid response formats are JSON, JSONP, JS or XML. Yes String
apiKey
Your TomTom API key. Yes String
[criteria] This is a JSON serialized deCarta.Core. RouteCriteria object (see our JavaScript API). Its structure is described below (Defaults are marked with '*''): No JSON Object
 
{
  //Unit for distance measurement.
  distanceUnit: ["KM","M","FT",*"MI"],

  //Provide a Route ID
  provideRouteID: [true, *false],

  //The directional heading of the vehicle in degrees, for travel along a segment of roadway. 0 is North, 90 is East and so on, values range from -360 to 360. The precision can include upto one decimal place.
  heading: 0,
  
  /*
   Routing Style
     
     Fastest: Computes the least cost route, considering road class. 
     Easy: Computes a fast route that avoids turns.
     NoFreeways: Computes a route without considering limited acccess roads (Freeways/Highways/Motorways)
     MoreFreeways: Favors freeways even if less costly routes are available.
     AvoidFreeways: Assigns a high cost to travel on limited access roads, so that they are used only if necessary to find a route.
     Pedestrian: Computes a pedestrian route.
     Shortest: Computes the shortest route without considering turns or the road class.
  */
  routePreference: [*"Fastest", "AvoidFreeways", "Easy", "MoreFreeways", "NoFreeways", "Pedestrian", "Shortest"],

  
  /*
    Array of waypoints to route through. (defaults to an empty array). 
    The maximum number of waypoints that can be passed in is 10. 
    If they have to be optimized the limit goes down to 5
  */
  waypoints: ["lat,Lon"],

  /*

   Pass in the name of the rules file to get maneuver instructions in different languages or styles.
   The name of the rules file for vehicles is of the format 'maneuver-rules-XX'.
   The name of the rules file for pedestrians is of the format 'maneuver-rules-pedestrian-XX'.
   The default style is for vehicles, The default language is English ('maneuver-rules-EN')
   
   Where XX is a 2 letter ISO language code, currently supported language codes: 
   
   AR (Arabic), BG (Bulgarian), CS (Czech), DA (Danish), DE (German), EL (Greek), EN (English), 
   ES (Spanish), FI (Finnish), HU (Hungarian), ID (Indonesian), IT (Italian), KO (Korean), 
   LT (Lithuanian), MS (Malay), NL (Dutch), NO (Norwegian), PL (Polish), RU (Russian), 
   SL (Slovene), SK (Slovak), SV (Swedish), TH (Thai), TR (Turkish), ZH (Traditional Chinese)

   In some cases where the locale could change the way the instructions look (Ex: British English),
   The name of the rules file for vehicles is of the format 'maneuver-rules-CC-XX'.
   The name of the rules file for pedestrians is of the format 'maneuver-rules-pedestrian-CC-XX'.
   Where CC is a 2 letter ISO country code and XX is a 2 letter ISO language code, currently supported locales:

   BE-FR (Belgium-French), BE-NL (Belgium-Dutch), BR-PT (Brazil-Portugese), 
   CH-DE (Switzerland-German), CH-FR (Switzerland-French), CH-IT (Switzerland-Italian),
   EG-AR (Egypt-Arabic), GB-EN (GreatBritain-English), LU-DE (Luxembourg-German), LU-FR (Luxembourg-French), 
   PT-PT (Portugal-Portugese), SA-AR (SaudiArabia-Arabic), VE-ES (Venezuela-Espanol), ZA-EN (SouthAfrica-English)

  */
  instructionRules:"maneuver-rules-EN",

  //If enabled, the route will consider live traffic conditions
  trafficEnabled: [true, *false],

  /*
    Specify an arrival time or departure time for the route to take into consideration, it will make use of historic traffic patterns when these attributes are passed in. Works only when 'trafficEnabled' is set to 'true'.  
    If both arrival and departure are present, api defaults to using arrivalTime.
  */
  arrivalTime: YYYY-MM-DDTHH:mm,

  departureTime: YYYY-MM-DDTHH:mm,


  /*
   Array of serialized shapes. The route will avoid intersecting these areas. 
   Ex: 
   {"type":"POLYGON","vertices":["37.75241,-122.43576","37.70660,-122.43301","37.71205,-122.36434"]}
   {"type":"CIRCLE","position":"44.99362,-74.08582", "radius":"300"} //radius in meters 
   {"type":"POLYLINE", "lineGeometry": ["37.75241,-122.43576", "37.70660,-122.43301"]}
   Currently only a Polygon (deCarta.Core.Polygon), Circle (deCarta.Core.Circle) and Polyline (deCarta.Core.Polyline)can be passed in for avoidance.
  */
  avoidAreas: [],

  //Road types to avoid. Defaults to empty array
  avoidList:["ferry","toll","tunnels","bridges","skyway","unpavedroad","limitedaccess"]

  //Adjusting costs for the above avoidList. The following parameter can only be passed in together with the avoidList. 
  //Ex: If 'toll' is pased in the avoidList, a corresponding cost can be passed in the adjustCost object. {"toll":10}.
  //The cost can either be a float number or a string 'INF' which assigns infinite cost.
  //If adjustCost is not passed in the defualt cost will be set to 'INF' for the avoidList
  adjustCost: {},

  //Number of alternate routes to return, a maximum of 2 alternate routes can be requested.
  alternateRoutes: 0,

  //If set to true, waypoints will be rearranged in optimal order. Maximum optimized waypoints that can be passed in is 5.
  optimized: false,

  //If set to true, each route instruction will include a link/url to a small map describing the maneuver, which can then later be fetched as needed
  maneuverMaps : false,

  //If requesting maneuver maps, further configuration of the map can be requested using the following object
  maneuverMapConfig : {
      "orientation":"heading-up", //Currently this is the only supported orientation
      "height":200,
      "width":200
  }
}

            

Response

Format

Response will be a json object, with the following structure:

{
  routeGeometry: [
    "37.33599, -121.88901",
    "37.33593, -121.88897",
    "37.33482, -121.88812",
    .....
    "37.3248, -121.90067",
    "37.32464, -121.90055",
    "37.32454, -121.90047",
    "37.32461, -121.90032",
    "37.32494, -121.89979",
    "37.32525, -121.89923"
  ],
  routeInstructions: {
    list: [
      {
        distance: {
          distance: 0,
          uom: "M"
        },
        tour: 0,
        duration: "PT0H0M0S",
        description: "route maneuver 1",
        Instruction: "Proceed Southeast on S 2nd St",
        turnAngle: 0.0
        Point: "37.33599, -121.88901"
      },
      ......
      {
        distance: {
          distance: 148.86,
          uom: "M"
        },
        tour: 0,
        duration: "P0DT0H0M9S",
        waitTime: "P0DT0H0M0S",
        description: "route maneuver 6",
        Instruction: "Arrive at destination",
        turnAngle: "0.0"
        Point: "37.32525, -121.89923",
        sideOfStreet: "Along"
        //other possible attributes
        isFork: true
        type: 'Roundabout' / 'Exit Ramp' / 'Entrance Ramp'
      }
    ],
    language: 'English'
  },
  routeSummary: {
    boundingBox: {
      points: null,
      topLeftPoint: "37.33599000000002, -121.90105000000001",
      btmRightPoint: "37.324540000000006, -121.88811999999999"
    },
    totalDistance: {
      distance: 2125.14,
      uom: "M"
    },
    totalTime: "P0DT0H3M33S",
    totalTravelTime: "P0DT0H3M33S",
    totalWaitTime: "P0DT0H0M0S"
  }
}