Detour and Turn Restrictions

Turn restrictions are rules in the map data that specify that vehicles are not allowed to turn from one road into another. Sometimes it is necessary to remove such a rule from the map data or add a new one.

Query Turn Restrictions

To remove or edit an existing turn restriction from the map data, you need the geometry and OpenLR code of the restriction. Use the endpoint [GET] /detour/turnrestrictions/{from}/{to} to query all turn restrictions in a bounding box with a diameter of up to 10 km from the map data.

This example selects the turn restrictions in the bounding box from 50.73614, 7.09503 to 50.73756, 7.09732 from the TomTom map data:

curl -X GET "https://api.maptrip.de/v1/detour/turnrestrictions/50.73614%2C7.09503/50.73756%2C7.09732?provider=tomtom" -H "accept: application/json" -H "Authorization: Bearer <token>"

The result is an array with a single turn restriction:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

[
  {
    "coordinates": [
    {
        "lat": 50.739887,
        "lon": 7.101973
      },
      {
        "lat": 50.739921,
        "lon": 7.101946
      },
      {
        "lat": 50.739915,
        "lon": 7.101892
      }
    ],
    "openlr": "CwUM/iQUuxLeAv+wAGczBw=="
  }
]

Remove existing Turn Restrictions

To remove an existing turn restriction, you first have to query its coordinate and OpenLR code from the map data. See Query turn restrictions for an example of how to query turn restrictions.

To ignore the turn restriction from the example above in route calculations, it is sent to the endpoint [POST] /detour/file/{fileid}/turnrestriction/remove:

curl -X "POST" "https://api.maptrip.de/v1/detour/file/1234/turnrestriction/remove?provider=TomTom" -H "accept: */*" -H "Authorization: Bearer <token>" -H "Content-Type: application/json" -d "{\"coordinates\": [{\"lat\": 50.739887,\"lon\": 7.101973},{\"lat\": 50.739921,\"lon\": 7.101946},{\"lat\": 50.739915,\"lon\": 7.101892}],\"openlr\": \"CwUM/iQUuxLeAv+wAGczBw==\"}"

Optionally, you can pass the attribute description, e.g. to add the position or the reason for the removed turn restriction:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

{
  "coordinates": [
    {
      "lat": 50.739887,
      "lon": 7.101973
    },
    {
      "lat": 50.739921,
      "lon": 7.101946
    },
    {
      "lat": 50.739915,
      "lon": 7.101892
    }
  ],
  "openlr": "CwUM/iQUuxLeAv+wAGczBw==",
  "attributes": [
    {
      "name": "description",
      "value": "This turn restriction is no longer used for route calculations"
    }
  ]
}

Edit existing Turn Restrictions

Using the endpoint [POST] /detour/file/{fileid}/turnrestriction/edit, you can edit the attributes of an existing turn restriction. This allows you to specify whether it should be used for normal routes, emergency routes or both.

First you have to query the coordinates and OpenLR code of the turn restriction to edit. See Query turn restrictions for an example.

Only two attributes are supported when editing turn restrictions: Use validity to specify for which types of routes this restriction should be used, and description to add a text describing this edit.

Here is an 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

{
  "coordinates": [
    {
      "lat": 50.737084,
      "lon": 7.096251
    },
    {
      "lat": 50.737072,
      "lon":7.096224
    },
    {
      "lat": 50.737089,
      "lon": 7.096206
    }
  ],
  "openlr": "CwUL2yQUaAr2AP/lAAc7DQ==",
  "attributes": [
    {
      "name": "description",
      "value": "Ignore for emergency routing"
    },
    {
      "name": "validity",
      "value": "26"
    }
  ]
}

curl -X "POST" "https://api.maptrip.de/v1/detour/file/1234/turnrestriction/edit?provider=TomTom" -H "accept: */*" -H "Authorization: Bearer <token>" -H "Content-Type: application/json" -d "{\"coordinates\":[{\"lat\":50.737084,\"lon\":7.096251},{\"lat\":50.737072,\"lon\":7.096224},{\"lat\":50.737089,\"lon\":7.096206}],\"openlr\":\"CwUL2yQUaAr2AP/lAAc7DQ==\",\"attributes\":[{\"name\": \"description\",\"value\":\"Ignore for emergency routing\"},{\"name\":\"validity\",\"value\":\"26\"}]}"

Add new Turn Restrictions

You can also add new turn restrictions to a Detour file. A turn restriction between road A and road B is defined by at least two coordinates: One on road A, and one on road B. Optionally, you can insert another coordinate at the intersection in between. For a new turn restriction, you must not set an OpenLR code. A list of attributes is optional, for now only description and validity are supported:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

{
  "coordinates": [
    {
      "lat": 50.738413,
      "lon": 7.101079
    },
    {
      "lat": 50.738591,
      "lon": 7.10165
    }
  ],
  "attributes": [
    {
      "name": "description",
      "value": "This is a new turn restriction for route calculations"
    },
    {
      "name": "validity",
      "value": "21"
    }
  ]
}

To create the new turn restriction, it has to be sent to the endpoint [POST] /detour/file/{fileid}/turnrestriction/add in the POST body:

curl -X "POST" "https://api.maptrip.de/v1/detour/file/1234/turnrestriction/add?provider=TomTom" -H "accept: */*" -H "Authorization: Bearer <token>" -H "Content-Type: application/json" -d "{\"coordinates\":[{\"lat\":50.738413,\"lon\":7.101079},{\"lat\":50.738591,\"lon\":7.10165}],\"attributes\":[{\"name\":\"description\",\"value\":\"This is a new turn restriction for route calculations\"},{\"name\":\"validity\",\"value\":\"21\"}]}"

Querying Turn Restrictions from a Detour File

There are two endpoints to query turn restrictions from a Detour file: [GET] /detour/file/{fileid}/turnrestriction/all returns all turn restrictions from the specified file, /detour/file/{fileid}/turnrestriction/{turnrestrictionid} just the one with the provided ID. Both endpoints return removed turn restrictions and added turn restrictions. See the attribute SegmentType to differentiate between them.

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

The (abbreviated) output looks like this:

 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

[
  {
    "id": 332657,
    "coordinates": [
      {
        "lat": 0,
        "lon": 0
      }
    ],
    "openlr": "CwUKGiQUHTvjBQCNAJMLCg==",
    "attributes": [
      {
        "name": "SegmentType",
        "value": "DeletedManeuver"
      },
      {
        "name": "description",
        "value": "Turn Restriction"
      },
      {
        "name": "editor_coordinates",
        "value": "7.089041611257949,50.73667164620194;7.089090997240569,50.73676541316029;7.088948229793389,50.73681059072612;7.089027314049545,50.73681801282303;7.088948229793389,50.73681059072612;7.0889862983793295,50.73676609656862"
      },
      {
        "name": "modify_MANEUVERS",
        "value": "delete"
      }
    ]
  },
  {
    "id": 332659,
    "coordinates": [
      {
        "lat": 50.73921,
        "lon": 7.084294
      },
      {
        "lat": 50.739085,
        "lon": 7.085129
      },
      {
        "lat": 50.739748,
        "lon": 7.085431
      }
    ],
    "openlr": "CwUJqCQUyzvqAgByADczMQI=",
    "attributes": [
      {
        "name": "SegmentType",
        "value": "AddedManeuver"
      },
      {
        "name": "description",
        "value": "Turn Restriction from Markthallen to Eifelstr."
      },
      {
        "name": "detourEditor_turnArrowCoords",
        "value": "7.084984377973187,50.73909128288187;7.085140865481373,50.73907195930009;7.085197289602957,50.73916633077078;7.0852169801134375,50.73911735228145;7.085197289602957,50.73916633077078;7.085131298284022,50.73913786943742"
      },
      {
        "name": "modify_MANEUVERS",
        "value": "add"
      }
    ]
  }
]

A single turn restriction from this example can be queried with its ID:

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

Deleting Turn Restrictions from a file

Both removed turn restrictions and added turn restrictions can be removed from a Detour file using the endpoint [DELETE] /detour/file/{fileid}/turnrestriction/{turnrestrictionid}. For example you can delete the removed turn restriction from the above example using its ID 332657:

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

Deleting a removed turn restriction restores the original behavior from the map data, i.e. turning is prohibited at this intersection.