Detour and new Roads

MapTrip Detour allows you to add roads to the map data. This can done with the Detour Editor and the MapTrip Server API. A new road, like a road segment, consists of a polyline of coordinates as well as attributes.

The following restrictions apply to the polyline:

only local roads can be created
the beginning or the end of the road or both must connect to an existing road
the road must not intersect itself
the road must not be shorter than 1 m
the road must not be longer than 1 km

Matching a Polyline to the Map Data

Since a new road must satisfy the above conditions, matching the polyline to the map data must first be performed.

In particular, the road must be connected to an existing road. This can originate from the original map data or also have been created via Detour. Therefore, the map provider and the ID of a Detour file is specified during matching.

Let's have a look at a new road which is defined by those four coordinates:

[
  {
    "lat":50.73657,
    "lon":7.09072
  },
  {
    "lat":50.73704,
    "lon":7.09103
  },
  {
    "lat":50.73738,
    "lon":7.09157
  },
  {
    "lat":50.73787,
    "lon":7.09059
  }
]

curl -X POST "https://api.maptrip.de/v1/detour/file/1234/road/match?provider=TomTom" -H "accept: application/json" -H "Authorization: Bearer <token>" -H "Content-Type: application/json" -d "[{\"lat\":50.73657,\"lon\":7.09072},{\"lat\":50.73704,\"lon\":7.09103},{\"lat\":50.73738,\"lon\":7.09157},{\"lat\":50.73787,\"lon\":7.09059}]"

The response indicates whether the start and end of the new road connect to existing roads:

{
  "start": true,
  "end": true
}

In this case, that is true for both the start and the end. Therefore, the new road can be created and used for route calculation.

Query Road Attributes

For new roads both a name and the driving direction (positive, negative or both) must be provided:

curl -X GET "https://api.maptrip.de/v1/detour/attribute/road?name=infoware%20Street&direction=both" -H "accept: application/json" -H "Authorization: Bearer <token>"

The response is an array of DetourSegmentAttribute objects for the new road:

[
  {
    "name": "MAP_TYPE",
    "value": "2"
  },
  {
    "name": "NAME",
    "value": "infoware Street"
  },
  {
    "name": "RS",
    "value": "0"
  },
  {
    "name": "TYPE",
    "value": "FCB"
  }
]

Additionaly you can add vehicle attributes like height restrictions.

Add a Road

After successful calls to both [POST] /detour/file/{fileid}/road/match and [GET] /detour/attribute/road, the new road can be created:

curl -X POST "https://api.maptrip.de/v1/detour/file/1234/road?provider=TomTom" -H "accept: */*" -H "Authorization: Bearer <token>" -H "Content-Type: application/json" -d "{\"attributes\": [{\"name\": \"MAP_TYPE\",\"value\": \"2\"},{\"name\": \"NAME\",\"value\": \"infoware Street\"},{\"name\": \"RS\",\"value\": \"0\"},{\"name\": \"TYPE\",\"value\": \"FCB\"}],\"coordinates\": [{\"lat\":50.73657,\"lon\":7.09072},{\"lat\":50.73704,\"lon\":7.09103},{\"lat\":50.73738,\"lon\":7.09157},{\"lat\":50.73787,\"lon\":7.09059}]}"

Use the MapTrip Detour edtitor to check the results:

Detour Editor: New Road

Update a Road

The endpoint [PUT] /detour/file/{fileid}/road/{roadid} can be used to overwrite the attributes of roads 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 road cannot be changed. If this is necessary, remove the old road and create a new one.

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

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

Delete a Road

If a newly created road is no longer needed, it can be deleted. This can be done with the endpoint [DELETE] /detour/file/{fileid}/road/{roadid}. You can delete the road 123456 in the file 1234 with this call:

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

If both the file and the road 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 newly created roads. To delete normal segments via Detour, see Deleting Detour Segments. To delete an existing road from the map data, see Delete Existing Roads.

Divide a Road

Suppose you want to change the properties of a road, but you only want this change to apply to part of the road. In this case it is necessary to divide it into two (or even more) parts using the endpoint [POST] /detour/file/{fileid}/segment/divide.

This endpoint has three parameters: The data provider, the Detour file, and the coordinate where the road should be divided:

curl -X "POST" "https://api.maptrip.de/v1/detour/file/1234/segment/divide?provider=TomTom" -H "accept: application/json" -H "Authorization: Bearer <token>" -H "Content-Type: application/json" -d "{ \"lat\": 50.736838, \"lon\": 7.092334 }"

In response you will get a DetourRoad object with the SegmentType CutPoint. Its coordinate is the point at which the road was divided:

{
  "created": [
    {
      "id": 123456,
      "coordinates": [
        {
          "lat": 50.73684467,
          "lon": 7.09231559
        }
      ],
      "attributes": [
        {
          "name": "MAP_TYPE",
          "value": "2"
        },
        {
          "name": "MapVersion",
          "value": "101420231115083527"
        },
        {
          "name": "SegmentType",
          "value": "CutPoint"
        },
        {
          "name": "detourEditor_created",
          "value": "2024-02-12T12:25:10Z"
        },
        {
          "name": "detourEditor_modified",
          "value": "2024-02-12T12:25:10Z"
        },
        {
          "name": "detourEditor_modifiedBy",
          "value": "user@example.org"
        },
        {
          "name": "fltSnapDist",
          "value": "5.000000"
        },
        {
          "name": "validity",
          "value": "0"
        }
      ]
    }
  ],
  "deleted": []
}

Now the MapTrip Detour edtitor will show the divided road in your file:

Detour Editor: Divided Road

Important

To join the parts again you have to call the endpoint [DELETE] /detour/file/{fileid}/road/{roadid} with the ID of the segment of type CutPoint (see Delete a Road).

Example: Add new Attributes to a divided Road

Important

This example is based on the previous one, assuming the road Weiherstraße has been divided at the coordinate 50.736838, 7.092334.

We will now add attributes to the southern part of Weiherstraße to close it for all traffic. This part goes from 50.736838, 7.092334 (where the road was divided) to 50.736375, 7.091956 (at Bornheimer Straße). This request matches these two coordinates to the southern part of the road:

curl -X "POST" "https://api.maptrip.de/v1/detour/file/1234/segment/match?provider=TomTom" -H "accept: application/json" -H "Authorization: Bearer <token>" -H "Content-Type: application/json" -d "[{ "lat": 50.736838, "lon": 7.092334 }, { "lat": 50.736375, "lon": 7.091956 }]"

{
  "coordinates": [
    {
      "lat": 50.73684467,
      "lon": 7.09231559
    },
    {
      "lat": 50.73680521,
      "lon": 7.09228002
    },
    {
      "lat": 50.73668582,
      "lon": 7.0921812
    },
    {
      "lat": 50.73635607,
      "lon": 7.09191171
    }
  ],
  "openlr": "CwULHiQUXDvzAf/Y/887Ag=="
}

Please note: When you send the same request body to a file without the divided street, it will return the road segment from Franzstraße to Bornheimer Straße instead.

To close the road segment, the attributes returned from the endpoint [GET] /detour/attribute/block are used:

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

To close the segment, send a request body containing both the match results and the attributes to the endpoint POST /detour/file/{fileid}/segment:

{
  "coordinates": [
    {
      "lat": 50.73684467,
      "lon": 7.09231559
    },
    {
      "lat": 50.73680521,
      "lon": 7.09228002
    },
    {
      "lat": 50.73668582,
      "lon": 7.0921812
    },
    {
      "lat": 50.73635607,
      "lon": 7.09191171
    }
  ],
  "openlr": "CwULHiQUXDvzAf/Y/887Ag==",
  "attributes": [
    {
      "name": "direction",
      "value": "3"
    },
    {
      "name": "mod_restriction",
      "value": "block"
    }
  ]
}

Use the MapTrip Detour edtitor to check the results:

Example: Delete a Part of a divided Road

Important

This example is based on the previous one, assuming the road Weiherstraße has been divided at the coordinate 50.736838, 7.092334.

We will now delete the southern part of Weiherstr. The request to match the coordinates to the road segment is the same as in the last example. Use the endpoint [GET] /detour/attribute/deleteroad to query the attributes to delete the road (see Delete Existing Roads).

The request body for [POST] /detour/file/{fileid}/segment with both the match results and the attributes looks like this:

{
  "coordinates": [
    {
      "lat": 50.73684467,
      "lon": 7.09231559
    },
    {
      "lat": 50.73680521,
      "lon": 7.09228002
    },
    {
      "lat": 50.73668582,
      "lon": 7.0921812
    },
    {
      "lat": 50.73635607,
      "lon": 7.09191171
    }
  ],
  "openlr": "CwULHiQUXDvzAf/Y/887Ag==",
  "attributes": [
    {
      "name": "ovld_RS",
      "value": "4095"
    },
    {
      "name": "detourEditor_deletedByUser",
      "value": "true"
    },
    {
      "name": "SegmentType",
      "value": "ExplicitlyDeletedOriginal"
    }
  ]
}

Again, you can use the MapTrip Detour edtitor to check the results:

Detour Editor: Divided and deleted Road