Skip to content

Route calculation

The MapTrip Server API provides route calculation functionality through the endpoint [GET] /route. A route is defined by:

  • summary: This includes essential details such as distance, driving time, and estimated time of arrival.
  • directions: Detailed driving instructions are provided, guiding users through the route (e.g., "Continue on this road for 4 km, then turn left...").
  • geometry: The route's path is represented by a series of coordinates.

Users can customize routes based on specific requirements by adjusting various parameters. These parameters may include vehicle type, dimensions, or preferences such as avoiding toll sections. Additionally, users can request multiple alternative routes simultaneously if needed.

Our system interacts with Detour to consider factors like blocked or unblocked road sections and turning restrictions.

It's important to note that all requests to this endpoint must include a valid Token for authentication. To test the endpoints in this tutorial, see the MapTrip Server API test page

Calculate a route

Requesting to [GET] /route

To initiate a route calculation request, the following minimum parameters are required:

  • provider (String): Indicates the map data provider. Possible values are TomTom, HERE, and OSM.
  • from (String; WGS84 decimal degrees (EPSG:4326)): Specifies the coordinates of the starting point.
  • to (String; WGS84 WGS84 decimal degrees (EPSG:4326)): Specifies the coordinates of the destination point.

Example curl command:

curl -X GET "https://api.maptrip.de/v1/route?provider=TomTom&from=50.73270%2C7.09630&to=50.94212%2C6.95781" -H "accept: application/json" -H "Authorization: Bearer <token>"

Example response

Please note that the response provided below is for example purposed only and is shortened for brevity.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
[
  {
    "summary": {
      "drivingTime": 2364,
      "length": 37643,
      "estimatedTimeOfArrival": "2021-07-06T15:41:24Z",
      "delay": 0,
      "toll": 0,
      "boundingBox": {
        "min": {
          "lat": 50.732695,
          "lon": 6.952754
        },
        "max": {
          "lat": 50.944504,
          "lon": 7.150814
        }
      }
    },
    "directions": [
      {
        "symbol": "start",
        "streetName": "Am Hauptbahnhof",
        "streetID": "",
        "connector": "",
        "signage": "",
        "distance": 102,
        "orientation": 301,
        "roundaboutExit": null,
        "coordinate": {
          "lat": 50.733093,
          "lon": 7.094993
        }
      },
      {
        "symbol": "roundabout",
        "streetName": "",
        "streetID": "K1",
        "connector": "",
        "signage": "",
        "distance": 368,
        "orientation": 51,
        "roundaboutExit": 2,
        "coordinate": {
          "lat": 50.734537,
          "lon": 7.090438
        }
      },
      {
        "symbol": "highway",
        "streetName": "",
        "streetID": "A555",
        "connector": "",
        "signage": "",
        "distance": 143,
        "orientation": 329,
        "roundaboutExit": null,
        "coordinate": {
          "lat": 50.743565,
          "lon": 7.077323
        }
      },
      {
        "symbol": "stayLeft",
        "streetName": "",
        "streetID": "A59",
        "connector": "",
        "signage": "Köln, A59",
        "distance": 14028,
        "orientation": 356,
        "roundaboutExit": null,
        "coordinate": {
          "lat": 50.881459,
          "lon": 7.094481
        }
      },
      ...
      {
        "symbol": "destination",
        "streetName": "",
        "streetID": "",
        "connector": "",
        "signage": "",
        "distance": 224,
        "orientation": 270,
        "roundaboutExit": null,
        "coordinate": {
          "lat": 50.942115,
          "lon": 6.957811
        }
      }
    ],
    "geometry": {
      "type": "FeatureCollection",
      "features": [
        {
          "type": "Feature",
          "id": 1,
          "geometry": {
            "type": "LineString",
            "coordinates": [
              [
                7.096295,
                50.7327
              ],
              [
                7.149386,
                50.780408
              ],
              ...
              [
                6.952808,
                50.936064
              ]
            ],
          },
          "properties": {}
        }
      ]
    }
  }
]

Important

Please note that the estimated time of arrival is represented as an ISO 8601 string in UTC (indicated by the trailing 'Z') and must be converted to your local time zone.

Route with waypoints

Waypoints serve to influence the trajectory of the route. We differentiate between intermediate destinations and via points:

  • Intermediate destinations: These must be reached in a similar manner to the final destination.
  • Via points: They are utilized to roughly define the route's trajectory. For instance, users can specify that the route should traverse through a particular city, highway, or on a specific side of a river

The distinction between a waypoint and a via point lies in the radius. If no radius is specified, it functions as an intermediate destination and requires precise navigation. Conversely, if a radius is specified, it becomes a via point, and the route must pass within that radius of the designated point.

For instance:

  • Using the coordinate 50.83821,7.09176 as a waypoint designates it as an intermediate destination.
  • Specifying 50.83821,7.09176,2000 converts the same coordinate into a via point with a radius of 2000 meters.

Request to [GET] /route

Upon executing the command from the previous example, waypoints are incorporated:

  • ** waypoints (List of Strings; WGS84 decimal degrees (EPSG:4326); semicolon separated)**:

    Multiple waypoints are provided as a semicolon-separated list. Each waypoint consists of latitude, longitude, and radius in meters.

Example:

50.8382171,7.0917674,500;51.7782142,7.0412278,500 (500 = radius in meters)

This command retrieves a route from the specified starting point to the destination while considering the provided waypoints.

Example curl command:

curl -X GET "https://api.maptrip.de/v1/route?provider=TomTom&from=50.73270%2C7.09630&to=50.94212%2C6.95781&waypoints=50.8382171%2C7.0917674%2C500;50.9222171%2C7.1017674%2C500" -H "accept: application/json" -H "Authorization: Bearer <token>"

Vehicle dependent route calculation

Route calculation can be customized based on vehicle types and dimensions, including weight considerations. This feature incorporates truck restrictions, clearance heights, tunnel limitations, and truck speeds into the calculation process. The metric system is utilized for dimensions, and weights are specified in kilograms. Decimal points are used for precision.

Request

To tailor navigation based on vehicle specifics, use the following parameters:

  • vehicle (String): Specifies the vehicle type. Possible values include:

  • car (default)

  • truck: A profile for trucks that prioritize highways over other roads.
  • truck_interurban: A profile for trucks that avoid highways.

  • width (Number, Double): Specifies the vehicle's width.

  • height (Number, Double): Specifies the vehicle's height.
  • length (Number, Double): Indicates the total length of the vehicle.
  • weight (Number, Double): Specifies the total weight of the loaded vehicle.
  • axles (Number, Double): Specifies the number of axes.
  • axleLoad (Number, Double): Specifies the weight per axle.

Example curl command:

curl -X GET "https://api.maptrip.de/v1/route?provider=TomTom&from=50.73270%2C7.09630&to=50.94212%2C6.95781&vehicle=fast&type=fastest&width=218&height=220&length=800&weight=25000&axles=5&axleLoad=8000" -H "accept: application/json" -H "Authorization: Bearer <token>"

This command retrieves a route from the specified starting point to the destination, considering the vehicle's dimensions and weight, and other specified parameters.

Obstacles along the route

In certain scenarios, a valid route may not be found for your specified vehicle and destination. However, you will still receive a route suggestion along with notes indicating road segments where potential issues may arise. These issues can stem from various reasons:

  • A road segment may not be suitable for your selected vehicle type (e.g., you requested a truck route, but a road segment is closed for trucks).
  • Your selected vehicle attributes may not align with the road segment requirements (e.g., the height or axle load of your vehicle exceeds the allowed maximum).
  • The destination might be situated in a pedestrian zone or a residential area.

In such cases, the route summary attribute hasObstacles will be set to true, and the attribute obstacles will contain a list of road segments where obstacles are present. Each obstacle includes a type, description, and coordinates of the affected road segment. It's important to note that a single road segment may have multiple obstacles.

We recommend checking for obstacles and determining whether they affect your route after each route calculation.

Example

Here's an example of the route summary with obstacles. In this instance, only one road segment is affected, but it encounters three different obstacles: the destination is within a pedestrian zone, within a resident-only area, and the vehicle type (truck) is prohibited on this road segment.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
{
  "drivingTime": 604,
  "length": 2120,
  "estimatedTimeOfArrival": "2022-05-27T15:16:12Z",
  "toll": 0,
  "boundingBox": {
    "min": {
      "lat": 50.938413,
      "lon": 6.947858
    },
    "max": {
      "lat": 50.945387,
      "lon": 6.960156
    }
  },
  "hasObstacles": true,
  "obstacles": [
    {
      "details": [
        {
          "type": "DESTINATION_IN_PEDESTRIAN_ZONE",
          "description": "Destination in pedestrian zone"
        },
        {
          "type": "DESTINATION_IN_RESIDENT_ONLY_AREA",
          "description": "Destination in resident only area"
        },
        {
          "type": "VEHICLE_TYPE_NOT_ALLOWED",
          "description": "Vehicle type not allowed on this road segment"
        }
      ],
      "roadsegment": {
        "type": "Feature",
        "geometry": {
          "type": "LineString",
          "coordinates": [
            [6.959895, 50.939206],
            [6.959967, 50.939104],
            [6.960066, 50.938827],
            [6.960129, 50.938583],
            [6.960156, 50.938413]
          ]
        },
        "properties": {
          "LENGTH": "90",
          "NAME": "Alter Markt"
        }
      }
    }
  ]
}

Traffic

Traffic Scenarios for Calculated Routes:

There are three traffic scenarios that can affect calculated routes: a time-independent route, a future route using statistical traffic information, and a route starting within the next 45 minutes utilizing real-time traffic data.

flowchart LR A{start time?} --> |no| noA["time independent route"] A --> |yes| B{"Start time in the next 45 minutes?"} B --> |no| bNo["statistical route"] B --> |yes| C{"Traffic?"} C --> |no| bNo C --> |yes| D["real time traffic"]

Time-independent route

  • If no start time is included, the server will provide a time independent route.

Example curl command (note the absence of traffic or start time):

curl -X GET "https://api.maptrip.de/v1/route?provider=TomTom&from=50.73270%2C7.09630&to=50.94212%2C6.95781" -H "accept: application/json" -H "Authorization: Bearer <token>"

Statistical traffic information

  • When a start time that is more than 45 minutes in the future is provided, the server employs statistical traffic information based on historical data.

Example curl command:

curl -X GET "https://api.maptrip.de/v1/route?provider=TomTom&from=50.73270%2C7.09630&to=50.94212%2C6.95781&traffic=true&startTime=2024-05-27T15:16:12Z" -H "accept: application/json" -H "Authorization: Bearer <token>"

Real-time traffic information

  • For routes starting NOW or within the next 45 minutes, MapTrip's real-time traffic data is available. If you want to calculate a route with live traffic, use the parameters traffic=true and either startTime=NOW or startTime= with an ISO 8601 string within the next 45 minutes. If you do not include traffic=true, the server will provide statistical traffic information.

  • Please note that as traffic situations change constantly, traffic information for the original request is only valid for approximately 45 minutes. Therefore, your application should send new requests to the server at set intervals along the route for constant traffic updates. Otherwise, the route will transition from real-time traffic to statistical traffic information after the initial request time is up.

Important

The server only obtains live traffic data from TomTom & HERE maps. OpenStreetMaps does not provide this information. If the provider is set to OSM, a status of 400 will be returned.

Example curl command:

curl -X GET "https://api.maptrip.de/v1/route?provider=TomTom&from=50.73270%2C7.09630&to=50.94212%2C6.95781&traffic=true&startTime=NOW" -H "accept: application/json" -H "Authorization: Bearer <token>"

Response

The format of the response corresponds to that of the first example. Note that if using real time traffic, the delay will be a number corresponding to the delay time in seconds.

Delay on the Route

When live traffic data is used, the discrepancy between the driving time considering live traffic and the standard driving time (derived from statistical traffic data) is returned in seconds within the "delay" field in the route summary.

For routes computed without live traffic data, the delay is indicated as 0.

Integrating Detour

A notable functionality of route calculation with the MapTrip Server API is the capability to incorporate closures, turn restrictions, and similar factors, which can be established using the Detour endpoints or the MapTrip Detour Editor.

For detailed information, see Detour and route calculation.

Emergency routing

When emergency routing is activated, route calculations disregard certain restrictions:

  • Turning restrictions are ignored.
  • One-way streets can be traversed in both directions.
  • Pedestrian areas become accessible.
  • Parks are accessible.

A specified radius in meters around the destination delineates where standard routing transitions to emergency routing. A radius of 0 deactivates emergency routing. By default, emergency routing is disabled.

Example curl command:

curl -X GET "https://api.maptrip.de/v1/route?provider=TomTom&from=50.73270%2C7.09630&to=50.94212%2C6.95781&emergencyRoutingRadius=1000" -H "accept: application/json" -H "Authorization: Bearer <token>"

Additional Options:

There are other features available for route calculation that can be optionally utilized. For detailed information on the options listed below, please refer to the Server API web page:

  • Route type
  • Alternative routes
  • Reference routes
  • Transport of hazardous goods, explosive materials, and materials harmful to water
  • Tunnel restrictions
  • Avoidance of tolls, highways, and ferries

Reference Routes

A reference route comprises a series of coordinates that delineate the path of a route. Typically, it is stored as a CSV file with columns for latitude (lat) and longitude (lon). Supplying a reference route to MapTrip ensures precise navigation along a predefined route course. Refer to the endpoint [POST] /remote/route/reference/{device} and the MapTrip Remote tutorial for more details.

The process of calculating a reference route closely resembles that of computing a regular route, with a few distinctions:

  • alternatives are not available for reference routes
  • the parameter joinGeometry is not available for reference routes
  • you can specify a distance in meters

When a distance is specified, the reference route comprises coordinates equidistant from each other at that specified distance. Otherwise, coordinates from the road data provider are used, which is recommended for employing reference routes in MapTrip.

Here is an example of generating a reference route from Bonn to Cologne with coordinates every 2 km:

Example curl command:

curl -X GET "https://api.maptrip.de/v1/route/reference?provider=TomTom&from=50.73270%2C7.09630&to=50.94212%2C6.95781&distance=2000" -H "accept: text/csv" -H "Authorization: Bearer <token>"

This command requests a reference route using TomTom as the provider, starting from coordinates in Bonn and ending in Cologne, with coordinates generated every 2 km.

Response

lat;lon
50.7327;7.096295
50.742969;7.078457
50.751509;7.054411
50.763044;7.032813
50.778549;7.01863
50.794673;7.006095
50.809057;6.989683
50.821073;6.968552
50.838225;6.966467
50.856116;6.968817
50.874054;6.969652
50.891971;6.967971
50.903634;6.980888
50.919736;6.968516
50.936916;6.963111
50.942115;6.957802

Important

Please note that the response format for reference routes it text/csv, not application/json like for most other endpoints.