Skip to content

Detour

The interface detour is used to integrate the detour functionality with own (server) applications.

Detour-Functionality

Detour allows to consider special rules during navigation with MapTrip.

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

In summary, Detour serves the

  • Closure of construction sites or road sections
  • Opening one-way streets
  • Opening pedestrian zones
  • Lifting and setting of turn prohibitions

When the following text refers to blockings in general, it also means unblockings, turn prohibitions, prioritizations, etc.

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).

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

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

Independently of the detour API interface, a web-based editor exists with which users can conveniently edit the locks.

detour-interface

Lock files

Regardless of whether editing is done via editor or interface, the rules are stored in so-called lock files.

A rule results from the adjustment of segments of the road network. Depending on the rule, individual or several consecutive segments may be affected. A blocking file is composed of a list of adjusted segments.

The segments are provided with

  • a single coordinate or
  • several coordinates (polyline)
  • the OpenLR code matching the coordinates
  • one or more attributes

Some attributes can be combined, others must be combined. For blocking a section, the direction is sufficient, for prioritization the 'routing cost' is additionally required.

For simplification, the attributes can be queried via corresponding interface functions.

Creation of a lock file step by step

  1. create a lock file
  2. Determine the OpenLR code to match the coordinates
  3. Querying the attributes
  4. Create the segments with

    • Coordinates
    • Attributes
    • OpenLR-Code

All commands to the interface require a valid Token.

Create a lock file

One or more rules are stored in the lock file.

Request

POST /detour/file

Parameters:

  • provider (String)

    Possible values (pay attention to exact spelling):

    • TomTom
    • HERE
    • OpenStreetMap
  • body (Json Body)

    The name of the file. See the notes on file naming in the documentation.

Example curl-Command

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

Response

1
2
3
4
5
6
{
  "id": 707,
  "name": "myDetourFile",
  "version": -1,
  "profile": "olrclient_MapTrip_Standard-Detour-File_73652_myDetourFile"
}

The id is needed later for the creation of the segments, but can of course also be queried later.

Determine OpenLR code

Based on coordinates, the interface provides the matching OpenLR code. At the same time, the coordinates are matched to the segments recorded in the map data.

The result is a list of all segments that represent the road segments selected in the request.

The OpenLR code contained in the response is later used to create the segments in the lock file.

Request

POST /detour/match

Parameters:

  • provider (String)

    Possible values (pay attention to exact spelling):

    • TomTom
    • HERE
    • OpenStreetMap
  • coordinate (Json Body)

    One or more WGS84 coded coordinates

    Example:

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    [
      {
        "lat": 50.70299488537384,
        "lon": 7.141086459159851
      },
      {
        "lat": 50.703283672221076,
        "lon": 7.140587568283081
      },
      {
        "lat": 50.70266532644585,
        "lon": 7.139230370521545
      },
      {
        "lat": 50.701448996126445,
        "lon": 7.140753865242004
      }
    ]
    

Example curl-command

curl -X POST "https://api.maptrip.de/v1/detour/match?provider=TomTom" -H "accept: application/json" -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9" -H "Content-Type: application/json" -d "[ { \"lat\": 50.70299488537384, \"lon\": 7.141086459159851 }, { \"lat\": 50.703283672221076, \"lon\": 7.140587568283081 }, { \"lat\": 50.70266532644585, \"lon\": 7.139230370521545 }, { \"lat\": 50.701448996126445, \"lon\": 7.140753865242004 }]"

Response

 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
{
  "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.

The interface provides the appropriate attributes for the type of locking, which can be queried from your own program and then inserted into the request to create the segment.

This simplifies the handling of the attributes, since e.g. to preferred sections (prioritize) or to avoided sections (penalize) not only the adjusted costs, but also the direction of travel.

Some of the requests do not require explicit data, but the responses contain sample data.

Request

GET /detour/attribute/{attribute}

The placeholder {attribute} can be for example (list not complete):

  • block
  • unblock
  • prioritize
  • vehicle/height
  • vehicle/length
  • vehicle/weight
  • vehicle/materialsharmfultowater

see also the documentation of the MapTrip Server API.

Example curl-command block

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

Example curl-command prioritize

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

Response

Example Response prioritize

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
[
  {
    "name": "priority",
    "value": "10"
  },
  {
    "name": "direction",
    "value": "3"
  }
]

Create a segment

By creating a segment within the blocking file, the desired road sections are provided with attributes, i.e. blockings.

In accordance with the examples before, a segment for the preferred use of a road section is created below.

Request

POST detour/file/{fileid}/segment

URL Placeholder:

  • fileid (Path)

    ID of the lock file. The ID was part of the response for creating the lock file. In addition, the ID can be determined by querying all available lock files.

Parameters:

  • provider (String)

    Possible values (pay attention to exact spelling):

    • TomTom
    • HERE
    • OpenStreetMap
  • detourSegment (Json Body)

    Example:

     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
    {
      "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="
    }
    

Example curl-command

curl -X POST "https://api.maptrip.de/v1/detour/file/707/segment?provider=TomTom" -H "accept: application/json" -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9" -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

 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
{
  "id": 9767,
  "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=",
  "attributes": [
    {
      "name": "direction",
      "value": "3"
    },
    {
      "name": "priority",
      "value": "10"
    }
  ]
}