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., "Turn right onto Great Russell Street" or "Take the second exit at the roundabout").
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: A string indicating the map data provider. Possible values are TomTom, HERE, and OSM.
from: A string with WGS84 decimal degrees (EPSG:4326)). Specifies the coordinates of the starting point.
to: A string with WGS84 decimal degrees (EPSG:4326)). Specifies the coordinates of the destination point.

This curl command fetches a route from Bonn to Cologne:

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.

[
  {
    "summary": {
      "name": "Via A555",
      "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",
        "text": "Start on Am Hauptbahnhof in direction north-west",
        "streetName": "Am Hauptbahnhof",
        "streetID": "",
        "connector": "",
        "signage": "",
        "distance": 0,
        "orientation": 299,
        "coordinate": {
          "lat": 50.732695,
          "lon": 7.096295
        }
      },
      {
        "symbol": "straightOn",
        "text": "Continue on Rabinstraße",
        "streetName": "Rabinstraße",
        "streetID": "",
        "connector": "",
        "signage": "",
        "distance": 123,
        "orientation": 306,
        "coordinate": {
          "lat": 50.733189,
          "lon": 7.094741
        }
      },
      {
        "symbol": "roundabout",
        "text": "Take the second exit at the roundabout",
        "streetName": "",
        "streetID": "K1",
        "connector": "",
        "signage": "",
        "distance": 349,
        "orientation": 44,
        "roundaboutExit": 2,
        "coordinate": {
          "lat": 50.734525,
          "lon": 7.090429
        }
      },
      ...
      {
        "symbol": "destination",
        "text": "Destination reached",
        "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.

Change the Language of the Driving Directions

The driving directions each have a textual description. These texts are in English by default. If you want to change the language, you have to add the HTTP header Accept-Language. Currently supported languages are English and German.

To get the same route as in the previous section, but with German texts, use this 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 "Accept-Language: de" -H "Authorization: Bearer <token>"

If the header contains several languages, the first supported language is used. All these values for Accept-Language return German texts:

de
de-DE
de-CH,en-US
fr-CH, fr;q=0.9, de;q=0.8

Route with waypoints

You can use waypoints for the route. We differentiate between intermediate destinations and via points:

Intermediate destinations must be reached like the final destination.
Via points are used to roughly define the course of the route. For instance, users can specify that the route should be calculated via a certain city or highway.

An intermediate destination is defined by a coordinate in WGS84 decimal degrees (EPSG:4326). It has the same format as the start and destination of the route, e,g, 50.83821,7.09176. A via point has an additional radius in meters: 50.83821,7.09176,1000 is a via point with a radius of 1 kilometer.

To use multiple waypoints for your route, use a semicolon separated list. This example shows an intermediate destination and a via point with a radius of 500 meters:

50.8382171,7.0917674,500;51.7782142,7.0412278,500

Here is an example of a route with two via points:

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%3B50.9222171%2C7.1017674%2C500" -H "accept: application/json" -H "Authorization: Bearer <token>"

Vehicle dependent route calculation

The route can be customized for a vehicle, its dimensions, weight and load. The following parameters help you to avoid roads, tunnels and bridges that you cannot or may not use with your vehicle:

vehicle: Specifies the vehicle type
- car (default): A profile for normal cars
- truck: A profile for trucks that prioritize highways over other roads. Routes tend to be faster, but have a longer distance with tolls
- truck_interurban: A profile for trucks that prioritize other roads over highways. Routes tend to be shorter and have less toll

width: The vehicle's width in meters
height: The vehicle's height in meters
length: The vehicle's length in meters
weight: The vehicle's weight in kilograms
axles: The number of axles of the vehicle
axleLoad: The vehicle's axle load in kilograms
hazardousGoods: true if the vehicle is transporting hazardous goods, false otherwise
explosiveMaterials: true if the vehicle is transporting explosive materials, false otherwise
materialsHarmfulToWater: true if the vehicle is transporting materials harmful to water, false otherwise
tunnelRestrictionCode: When your vehicle is transporting hazardous goods and has a tunnel restriction code, you can provide it to avoid certain tunnels
lowEmissionZones and lezVignette : When lowEmissionZones is set to true, low emission zones are taken into account. In this case, you must also specify the vignette (None, Red, Yellow, Green) using the parameter lezVignette

This example calculates a route for a truck with a width of 2.45 meters, a height of 2.8 meters, a weight of 25 tons (i.e. 25000 kilograms), 5 axles, an axle load of 8 tons, and a load hazardous to water:

curl -X GET "https://api.maptrip.de/v1/route?provider=TomTom&from=50.73270%2C7.09630&to=50.94212%2C6.95781&vehicle=truck&width=2.45&height=2.8weight=25000&axles=5&axleLoad=8000&materialsHarmfulToWater=true" -H "accept: application/json" -H "Authorization: Bearer <token>"

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.

{
  "name": "Via A555",
  "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 Parameters

These additional parameters influence the behavior of the routing:

type: By default, you'll get the fastest route from the start to destination. If you want to use the shortest route instead, specify the parameter type=shortest
alternatives: You can calculate up to two alternatives for your route. If you specify the parameter alternatives=2, you will get an array of three routes, sorted by the driving time from fastest to slowest.
avoidToll: You can set this parameter to true to avoid roads with toll
avoidFerries: You can set this parameter to true to avoid ferries
avoidHighways: You can set this parameter to true to avoid highways. This must not be used for routes which are longer than 100 kilometers
useTurnRestrictions: By setting this parameter to true, you can totally ignore turn restrictions from the map data provider. If, for example, it is not permitted to turn left at a junction, with useTurnRestrictions=true the route will take the turn anyway. If you are not absolutely sure, do not set this parameter to true!
joinGeometry: By default, the geometry of all road segments is joined to a single polyline in the response to easily render it in a map. You can prevent this by specifying joinGeometry=false

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.