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
1 2 3 4 5 6 | |
The id is needed later for the creation of the segments, but can of course also be queried later.
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 array of coordinates looks like this:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | |
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.
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 | |
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:
1 2 3 4 5 6 7 8 9 10 | |
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).
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 | |
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.
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 | |
Deleting Detour Segments
If a change made with the Detour API is no longer 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 and the segment 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.
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 do so, pass an array with the new attributes.
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 or detourEditor_created. So you should pass these when calling this endpoint.
The coordinates of the segment cannot be changed. If this 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\" } ]"
Query the Contents of a Detour File
A Detour file can contain both segments with attributes and new roads. There are four endpoints to query the contents of a file:
[GET] /detour/file/{fileid}/segment/allreturns all segments in the file[GET] /detour/file/{fileid}/segment/{segmentid}returns one segment in the file[GET] /detour/file/{fileid}/road/allreturns all new roads in the file[GET] /detour/file/{fileid}/road/{roadid}returns one new road in the file
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>"
[
{
"id": 124171,
"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 in the file is done like this:
curl -X GET "https://api.maptrip.de/v1/detour/file/1234/road/all?provider=TomTom" -H "accept: application/json" -H "Authorization: Bearer <token>"
[
{
"id": 146845,
"coordinates": [
{
"lat": 50.736527,
"lon": 7.090933
},
{
"lat": 50.736774,
"lon": 7.090947
},
{
"lat": 50.737317,
"lon": 7.091582
},
{
"lat": 50.737868,
"lon": 7.090609
}
],
"attributes": [
{
"name": "MAP_TYPE",
"value": "2"
},
{
"name": "NAME",
"value": "infoware Street"
},
{
"name": "RS",
"value": "0"
},
{
"name": "TA",
"value": ""
},
{
"name": "TYPE",
"value": "FCB"
}
]
}
]
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>"
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | |
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/deviceslists the IDs all your devices configured for Detour[GET] /detour/devices/detailslists details of all your devices configured for Detour[GET] /detour/maptrip/activefilereturns the Detour file which is active for MapTrip[POST] /detour/maptrip/activefilesets the Detour file which is active for MapTrip[DELETE] /detour/maptrip/activefiledeactivates 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>"
1 2 3 4 5 6 | |
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:
1 2 3 4 | |
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:
1 2 3 4 5 6 7 8 9 | |
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.