Detour Basics

The endpoints described in this section are used to integrate MapTrip Detour functionality with own applications.

Definition

Detour allows changing the properties of road segments. Roads changed in this way can be taken into account in route calculation and in navigation with MapTrip.

Detour is mostly used for rescue vehicles and heavy-duty transports, but other fields of application are conceivable.

In summary, Detour allows you to

Close entire sections of roads (e.g. construction sites)
Open one-way streets or pedestrian zones for a route
Prioritize or penalize roads based on your experience (e.g. because they have a high risk of delays)
Add vehicle attributes like width, height or axle load to road segments
Add new roads which are missing in the map data
Add new turn restrictions to the map data or remove existing ones

Furthermore, the adjustments can be provided with start and end times or activated and deactivated in intervals (e.g. recurring on certain days at defined times). For a list of attributes, see Detour Attributes.

In addition to the MapTrip Server API, there is a web-based editor that allows users to conveniently edit map data.

Important

All changes made in the MapTrip Detour Editor are also visible in the MapTrip Server API and vice versa.

Providers and OpenLR

Depending on the provider, the coordinates of road sections can differ greatly between providers (TomTom, HERE, Open Street Map). Therefore, the provider of the maps installed on the navigation devices must be specified when creating the closures.

To store road segments independent of the provider we use OpenLR. A matching is performed for each road segment: The passed coordinates are mapped to an OpenLR code and the road segments of the selected provider. These data are stored in the Detour File.

Detour Files

Regardless of whether editing is done via editor or the MapTrip Server API, the data is stored in so-called Detour files.

A Detour file consists of a list of road segments with attributes. Every segment is defined by

a single coordinate or several coordinates (i.e. a polyline)
the OpenLR code matching the coordinates
a non-empty list of attributes

Creation of a Detour file step by step

Create a Detour file
For every Detour segment you want to add to the file:
- Match the coordinates of the segment to the map data and query an OpenLR code
- Query the attributes for this segment
- Create the segment with coordinates, the OpenLR code and the attributes
Optional: Use the file for route calculations and in MapTrip.

All commands to the API endpoints require a valid Token.

Create a Detour file

You can create a new Detour file with the endpoint [POST] /detour/file. This endpoint has two parameters: The provider of the map data you are using (i.e. TomTom, HERE or OpenStreetMap, pay attention to exact spelling) and the name of the file. The file name has to be in the POST body:

curl -X POST "https://api.maptrip.de/v1/detour/file?provider=TomTom" -H "accept: application/json" -H "Authorization: Bearer <token>" -H "Content-Type: text/plain" -d "myDetourFile"

Response

{
  "id": 1234,
  "name": "myDetourFile",
  "version": -1,
  "profile": "olrclient_MapTrip_Standard-Detour-File_73652_myDetourFile"
}

The id is needed later for the creation of the segments. You can get a list of all of your files using the endpoint [GET] /detour/file/all

Determine OpenLR code

The endpoint [POST] /detour/match is used to match an array of coordinates to road segments of the map data and the matching OpenLR code. The OpenLR code is needed to create any additional segments in the Detour file.

The array of coordinates looks like this:

[
  {
    "lat": 50.702994,
    "lon": 7.141086
  },
  {
    "lat": 50.703283,
    "lon": 7.140587
  },
  {
    "lat": 50.702665,
    "lon": 7.139230
  },
  {
    "lat": 50.701448,
    "lon": 7.140753
  }
]

Request to [POST] /detour/match

curl -X POST "https://api.maptrip.de/v1/detour/match?provider=TomTom" -H "accept: application/json" -H "Authorization: Bearer <token>" -H "Content-Type: application/json" -d "[ { \"lat\": 50.702994, \"lon\": 7.141086 }, { \"lat\": 50.703283, \"lon\": 7.140587 }, { \"lat\": 50.702665, \"lon\": 7.139230 }, { \"lat\": 50.70144, \"lon\": 7.140753 }]"

Response

The result is a list of all segments that represent the coordinates in the request. It can be used to create the segment in the Detour file.

{
  "coordinates": [
    {
      "lat": 50.702323,
      "lon": 7.142172
    },
    {
      "lat": 50.702692,
      "lon": 7.141642
    },
    {
      "lat": 50.703301,
      "lon": 7.140564
    },
    {
      "lat": 50.702675,
      "lon": 7.139217
    },
    {
      "lat": 50.701594,
      "lon": 7.140609
    },
    {
      "lat": 50.701446,
      "lon": 7.140798
    },
    {
      "lat": 50.701418,
      "lon": 7.140861
    },
    {
      "lat": 50.701412,
      "lon": 7.140933
    },
    {
      "lat": 50.701424,
      "lon": 7.140996
    },
    {
      "lat": 50.701622,
      "lon": 7.141356
    }
  ],
  "openlr": "CwUUMSQOEzP8Cf+z/7w7NAI="
}

Query attributes

Part of a segment in a Detour file are the attributes which define the type of modification (e.g. blocked, unblocked or prioritized).

The API provides endpoints to query the appropriate attributes. For a list of available attributes see Detour Attributes.

Example curl command block:

curl -X GET "https://api.maptrip.de/v1/detour/attribute/block?direction=both" -H "accept: application/json" -H "Authorization: Bearer <token>"

Example curl command prioritize with default value:

curl -X GET "https://api.maptrip.de/v1/detour/attribute/prioritize" -H "accept: application/json" -H "Authorization: Bearer <token>"

Example curl command prioritize with only slightly increased priority:

curl -X GET "https://api.maptrip.de/v1/detour/attribute/prioritize?value=2" -H "accept: application/json" -H "Authorization: Bearer <token>"

Response

This is an example response for a prioritize request with default value:

[
  {
    "name": "priority",
    "value": "10"
  },
  {
    "name": "direction",
    "value": "3"
  }
]

Create a segment

By creating a segment within the Detour file, the provided attributes (e.g. blocked, unblocked, height restriction) are stored for a road segment. This is done with the endpoint [POST] /detour/file/{fileid}/segment.

This example shows how to add a priority attribute to a road segment to prefer this road in route calculation and navigation. The highlighted lines are the results from the last two steps (see Determine OpenLR code and Query attributes).

{
  "attributes": [
  {
    "name": "priority",
    "value": "10"
  },
  {
    "name": "direction",
    "value": "3"
  }
  ],
  "coordinates": [
    {
      "lat": 50.702323,
      "lon": 7.142172
    },
    {
      "lat": 50.702692,
      "lon": 7.141642
    },
    {
      "lat": 50.703301,
      "lon": 7.140564
    },
    {
      "lat": 50.702675,
      "lon": 7.139217
    },
    {
      "lat": 50.701594,
      "lon": 7.140609
    },
    {
      "lat": 50.701446,
      "lon": 7.140798
    },
    {
      "lat": 50.701418,
      "lon": 7.140861
    },
    {
      "lat": 50.701412,
      "lon": 7.140933
    },
    {
      "lat": 50.701424,
      "lon": 7.140996
    },
    {
      "lat": 50.701622,
      "lon": 7.141356
    }
  ],
  "openlr": "CwUUMSQOEzP8Cf+z/7w7NAI="
}

To create the segment you also have to provide the map data provider and the ID of the file you have created.

Example curl command:

curl -X POST "https://api.maptrip.de/v1/detour/file/1234/segment?provider=TomTom" -H "accept: application/json" -H "Authorization: Bearer <token>" -H "Content-Type: application/json" -d "{ \"attributes\": [ { \"name\": \"priority\", \"value\": \"10\" }, { \"name\": \"direction\", \"value\": \"3\" } ], \"coordinates\": [ { \"lat\": 50.702323, \"lon\": 7.142172 }, { \"lat\": 50.702692, \"lon\": 7.141642 }, { \"lat\": 50.703301, \"lon\": 7.140564 }, { \"lat\": 50.702675, \"lon\": 7.139217 }, { \"lat\": 50.701594, \"lon\": 7.140609 }, { \"lat\": 50.701446, \"lon\": 7.140798 }, { \"lat\": 50.701418, \"lon\": 7.140861 }, { \"lat\": 50.701412, \"lon\": 7.140933 }, { \"lat\": 50.701424, \"lon\": 7.140996 }, { \"lat\": 50.701622, \"lon\": 7.141356 } ], \"id\": 1337, \"openlr\": \"CwUUMSQOEzP8Cf+z/7w7NAI=\"}"

Response

The response looks like the POST body, but contains an ID for this segment. This can be used to query, update or delete the segment.

{
  "id": 123456,
  "coordinates": [
    ...
  ],
  "openlr": "CwUUMSQOEzP8Cf+z/7w7NAI=",
  "attributes": [
    ...
  ]
}

Updating Detour Segments

The endpoint [PUT] /detour/file/{fileid}/segment/{segmentid} can be used to overwrite the attributes of segments that you have added to a Detour file. To update detour segments, pass an array with the new attributes you want to overwrite.

Please note that coordinates of the segment cannot be changed. If changing the coordinates is necessary, remove the old segment and create a new one.

This example replaces all attributes of the segment 123456 in the file 1234 by a single direction attribute:

curl -X "PUT" "https://api.maptrip.de/v1/detour/file/1234/segment/123456?provider=TomTom" -H "accept: */*" -H "Authorization: Bearer <token>" -H "Content-Type: application/json" -d "[ { \"name\": \"direction\", \"value\": \"1\" }, { \"name\": \"SegmentType\", \"value\": \"Prioritize\" }, { \"name\": \"detourEditor_created\", \"value\": \"2024-10-24T12:24:56Z\" } ]"

If the segment is updated, the response code is a 200 OK without content.

Important

All attributes that were previously present and are missing in the passed array are removed. This also applies to automatically generated attributes like SegmentType and detourEditor_created. So you should pass these when calling this endpoint.

Deleting Detour Segments

If a change made with the Detour API no longer needs to be considered in route calculation and navigation, the segment can be deleted. This can be done with the endpoint [DELETE] /detour/file/{fileid}/segment/{segmentid}. You can delete the segment 123456 in the file 1234 with this call:

curl -X DELETE "https://api.maptrip.de/v1/detour/file/1234/segment/123456?provider=TomTom" -H "accept: */*" -H "Authorization: Bearer <token>"

If both the file 1234 and the segment 123456 exist, the response code is a 200 OK without content; otherwise, check the response for details:

{
  "status": 404,
  "errors": [
    "File does not exist"
  ]
}

Important

This endpoint can only be used to delete segments. To delete newly created roads via Detour, see Delete a Road. To delete an existing road from the map data, see Delete Existing Roads.

Query the Contents of a Detour File

A Detour file can contain segments with attributes, new roads and turn restrictions. There are endpoints to query all the contents of a file, all the contents with attributes matching a value, or a single item by an ID.

Query all Contents

These endpoints can be used to query all the contents of a Detour file:

[GET] /detour/file/{fileid}/segment/all returns all segments in the file
[GET] /detour/file/{fileid}/road/all returns all created roads in the file (see see Roads)
[GET] /detour/file/{fileid}/turnrestriction/all returns all turn restrictions in the file (see see Turn Restrictions)

Assuming you have a file with the ID 1234, you can query the segments in the file like this:

curl -X GET "https://api.maptrip.de/v1/detour/file/1234/segment/all?provider=TomTom" -H "accept: application/json" -H "Authorization: Bearer <token>"

The result is a list of segments:

[
  {
    "id": 123456,
    "coordinates": [
      {
        "lat": 50.737743,
        "lon": 7.107111
      },
      {
        "lat": 50.737937,
        "lon": 7.108549
      },
      {
        "lat": 50.738164,
        "lon": 7.110183
      },
      {
        "lat": 50.73863,
        "lon": 7.113516
      },
      {
        "lat": 50.738684,
        "lon": 7.113883
      }
    ],
    "openlr": "CwUNzyQUhgonCAKnAF4KNwE=",
    "attributes": [
      {
        "name": "direction",
        "value": "3"
      },
      {
        "name": "speed",
        "value": "0"
      }
    ]
  }
]

Querying the roads and turn restrictions in the same file is done with

curl -X GET "https://api.maptrip.de/v1/detour/file/1234/road/all?provider=TomTom" -H "accept: application/json" -H "Authorization: Bearer <token>"

and

curl -X GET "https://api.maptrip.de/v1/detour/file/1234/turnrestriction/all?provider=TomTom" -H "accept: application/json" -H "Authorization: Bearer <token>"

Query Detour File Segments by Attribute Values

By using the optional parameter query of the endpoints [GET] /detour/file/{fileid}/segment/all, [GET] /detour/file/{fileid}/road/all and [GET] /detour/file/{fileid}/turnrestriction/all, you can filter the result by the values of an attribute.

A query string has the form attribute:value, e.g. description:blocked. The value can contain the wildcard operator * to match zero or more characters: b*ed matches bed, blocked, bundled and so on. You can use term* for a prefix, *term for a suffix, and *term* to match everything which contains the term.

Let's assume the detour file with the ID 1234 contains segments with these values of the attribute descriptions:

blocked road
blocked (temporary)
main street blocked
temporary prioritized
weight limit
width limit (temporary)

To query all the temporary segments of the file, you can use the query parameter query=description:*temporary*:

curl -X GET "https://api.maptrip.de/v1/detour/file/1234/segment/all?provider=TomTom&query=description:*temporary*" -H "accept: application/json" -H "Authorization: Bearer <token>"

This will return segments 2, 4 and 6.

Accordingly, query=description:blocked* selects all segments whose description starts with blocked, i.e. segment 1 and 2, but not segment 3.

You can query not only the attribute description, but all attributes of your file:

query=SegmentType:block finds all blocked segments
query=detourEditor_created:*2024* finds all segments that were created in 2023
query=detourEditor_modifiedBy:user@example.org finds all segments which were created or modified by this user

Query Contents by ID

If you know the ID of a segment, road or turn restriction, you can query it with these endpoints:

[GET] /detour/file/{fileid}/segment/{segmentid} returns one segment in the file
[GET] /detour/file/{fileid}/road/{roadid} returns one created road in the file
[GET] /detour/file/{fileid}/turnrestriction/{turnrestrictionid} returns one turn restriction in the file

For example, a road with the ID 123456 in the file 1234 can be queried with

curl -X GET "https://api.maptrip.de/v1/detour/file/1234/road/123456?provider=TomTom" -H "accept: application/json" -H "Authorization: Bearer <token>"

Detour and Route Calculation

Changes to road segments made with MapTrip Detour can be taken into account when calculating routes. For this purpose, the file to be used must be passed as a parameter.

Important

Changes made with the API must first be applied to the routing. This is done automatically, but takes a short moment. Your routes will be available in the routing after about 10-20 seconds.

These endpoints have a detourFile parameter:

[GET] /route
[GET] /route/reference
[POST] /matrix/sync
[POST] /matrix/async
[POST] /optimize/stops

Let's assume your Detour files look like this:

curl -X GET "https://api.maptrip.de/v1/detour/file/all?provider=TomTom" -H "accept: application/json" -H "Authorization: Bearer <token>"

[
  {
    "id": 1623,
    "name": "Closed_Bridges",
    "version": 7,
    "profile": "olrclient_MapTrip_Server API_78309_Closed_Bridges"
  },
  {
    "id": 1601,
    "name": "default",
    "version": -1,
    "profile": "olrclient_MapTrip_Server API_78309_default"
  }
]

To use the file Closed_Bridges when calculating a route, you must pass the attribute profile to the endpoint [GET] /route:

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

Detour and MapTrip

To use Detour Files with MapTrip, they must be activated. By activating the file, it will be synchronized to all devices that can be used with Detour and will be used for every route calculation.

Important

Please note that only one file can be activated at a time. When you activate a file, previously activated files are automatically deactivated.

Automated synchronization of Detour files with MapTrip navigation devices ensures that they are considered in route calculation.

For the use with MapTrip, the following endpoints may be of interest:

[GET] /detour/devices lists the IDs all your devices configured for Detour
[GET] /detour/devices/details lists details of all your devices configured for Detour
[GET] /detour/maptrip/activefile returns the Detour file which is active for MapTrip
[POST] /detour/maptrip/activefile sets the Detour file which is active for MapTrip
[DELETE] /detour/maptrip/activefile deactivates all files for MapTrip

To activate the file Closed_Bridges from the last example, you have to call the endpoint [POST] /detour/maptrip/activefile with the ID of the file:

curl -X POST "https://api.maptrip.de/v1/detour/maptrip/activefile?provider=TomTom" -H "accept: */*" -H "Authorization: Bearer <token>" -H "Content-Type: text/plain" -d "1234"

A following call to the endpoint [GET] /detour/maptrip/activefile returns the file:

curl -X GET "https://api.maptrip.de/v1/detour/maptrip/activefile?provider=TomTom" -H "accept: application/json" -H "Authorization: Bearer <token>"

{
  "id": 1234,
  "name": "Closed_Bridges",
  "version": 7,
  "profile": "olrclient_MapTrip_Server API_78309_Closed_Bridges"
}

To stop using this file in MapTrip, you have to call the endpoint [DELETE] /detour/maptrip/activefile:

curl -X DELETE "https://api.maptrip.de/v1/detour/maptrip/activefile?provider=TomTom" -H "accept: */*" -H "Authorization: Bearer <token>"

Since no file is active after that, another call to the endpoint [GET] /detour/maptrip/activefile returns the status 404 Not Found.

Checking the Connectivity of a Detour File

Map data becomes outdated over time. For this reason, we regularly provide new map data. When this happens, you should check if your files need to be updated as well. This can have several reasons, including:

the coordinates of a segment which you have added to your Detour file have been changed in the map data
a road which you have added to your Detour file is no longer connected to the map data as the coordinates of other roads have been changed
a road which you have added to your Detour file was added to the map data
a road which has been deleted in your Detour file does no longer exist in the map data

You can use the endpoint [GET] /detour/file/{fileid}/connectivity to check your files. The endpoint returns a boolean value updateRequired indicating whether you need to update your file or not. In the first case, you also get a list of segments that need to be updated and a description of what needs to be adjusted per segment.

To check the file with the ID 1234 and TomTom data, you can call the endpoint like this:

curl -X POST "https://api.maptrip.de/v1/detour/file/1234/connectivity?provider=TomTom" -H "accept: */*" -H "Authorization: Bearer <token>" -H "Content-Type: text/plain" -d "1234"

For a file which does not need to be updated, the result looks like this:

{
  "updateRequired": false,
  "segments": []
}

This is an example of a file containing a segment which has to be updated as the coordinates of the road have changed in the map data:

{
  "updateRequired": true,
  "segments": [
    {
      "id": 123456,
      "description": "Olr geometry inner difference"
    }
  ]
}

In this case, you should open the file in the MapTrip Detour Editor. Log in with your user name and password and open the Detour file with connectivity problems. You should get a notification that your file is not using the latest map data and needs to be checked. Click on Verification here in the settings menu to check and update your file.