Skip to content

Detour Attributes

The properties of a road segment are defined by its attributes. So, to change a segment you must first compile a list of the desired attributes.

Block and Open

These are the most basic attributes: [GET] /detour/attribute/block blocks this road segment for all vehicles and [GET] /detour/attribute/open opens it for all vehicles. The latter can be used to open roads like one-way streets or pedestrian zones that you may use exceptionally.

Both endpoints have a direction parameter which can be positive (i.e. in the direction of the coordinates of the segment as you have provided them), negative or both.

For temporary changes to the map data block and open can be combined with Time Domains.

Speed

All road segments have individual speeds, which are derived from the road data of the provider used. These are used for route calculations if no live data is available (see Traffic).

You can overwrite them with the endpoint [GET] /detour/attribute/speed. There is one mandatory parameter: The value speed specifies the desired average speed on this segment in km/h. With the optional value delay, you can also specify an additional delay in seconds that occurs on this segment, e.g. at a level crossing or to remove bollards to allow passage. The parameter direction can be positive (i.e. in the direction of the coordinates of the segment as you have provided them), negative or both. It is optional and defaults to both.

If you are using the Detour Editor to view or update Detour files, you should also provide the parameter originalSpeed which should contain the original speed from the map data. To check these speeds, see Querying Road Segments.

This example shows how to reduce the speed on a segment from 25 km/h to 15 km/h and also adds a delay of a minute:

curl -X GET "https://api.maptrip.de/v1/detour/attribute/speed?speed=15&delay=60&originalSpeed=25" -H "accept: application/json" -H "Authorization: Bearer <token>"

The resulting attributes will look like this:

[
  {
    "name": "SegmentType",
    "value": "ModifiedSpeed"
  },
  {
    "name": "NewSpeed",
    "value": "15"
  },
  {
    "name": "Delay",
    "value": "60"
  },
  {
    "name": "detourEditor_originalRoadSpeed",
    "value": "25"
  }
]

By assigning a slower speed and a delay to the road segment, the segment is less likely to be used in a route calculation.

Note

It is important to note that changing the speed of a segment impacts the calculated travel time of your route. If you want to strongly prioritze or avoid a route, set the speed to dramatically increased or decrease travel speeds. For example, multiplying the base speed by 10 will increase the priority by 10x. The same is true for decreasing the priority: base speed x 0.1 will decrease the priority by 0.1x.

Prioritize and Penalize

Deprecated endpoints

These endpoints are deprecated and will be removed in one of the upcoming releases. Use [GET] /detour/attribute/speed with a high speed to prioritize a segment and a low speed or delay to avoid it.

With the endpoints [GET] /detour/attribute/prioritize and [GET] /detour/attribute/penalize, you can prioritize roads based on your experience with the traffic situation. A road segment with prioritize will be preferred for route calculation and a segment with penalize will be avoided.

These endpoints have a priority parameter which can differ from 2 (slightly increased priority) to 10 (strongly increased priority) for prioritize and from 0.1 (strongly decreased priority) to 0.9 (slightly decreased priority) for penalize.

The second parameter direction can be positive (i.e. in the direction of the coordinates of the segment as you have provided them), negative or both. It is optional and defaults to both.

Important

We strongly recommend using the parameter direction all the time. It must be present for one-way streets in particular, as the default value both would open and prioritize the road in both directions.

Vehicle Attributes

You can use Detour to block road segments for certain vehicles based on their size, weight or load. Examples include a width restriction for a narrow alley, a height restriction for an underpass, a maximum weight for a bridge, or a tunnel which must not be used with hazardous materials.

So-called vehicle attributes are used for this purpose. These vehicle attributes are supported:

  • [GET] /detour/attribute/vehicle/width: Adds a width limit to this segment
  • [GET] /detour/attribute/vehicle/height: Adds a height limit to this segment
  • [GET] /detour/attribute/vehicle/length: Adds a length limit to this segment
  • [GET] /detour/attribute/vehicle/weight: Adds a weight limit to this segment
  • [GET] /detour/attribute/vehicle/axleload: Adds an axle load limit to this segment
  • [GET] /detour/attribute/vehicle/axles: Limits the maximum number of axles for this segment
  • [GET] /detour/attribute/vehicle/hazardousgoods: Blocks this segment for vehicles transporting hazardous goods
  • [GET] /detour/attribute/vehicle/explosivematerials: Blocks this segment for vehicles transporting explosive materials
  • [GET] /detour/attribute/vehicle/materialsharmfultowater: Blocks this segment for vehicles transporting materials harmful to water
  • [GET] /detour/attribute/vehicle/tunnelRestrictionCode: Sets a tunnel restriction code for this segment

Of course, you can also assign several vehicle attributes for a road segment, for example, a width and height restriction and a tunnel code for a tunnel. To do this, query all attributes separately and merge them into an array when creating the segment.

Example: Height Restriction

Suppose you want to create a height limit of 3.8 meters for a road segment, retrieve the attribute via endpoint [GET] /detour/attribute/vehicle/height and pass the desired height in meters:

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

The response is a DetourSegmentAttribute which can be assigned to a segment:

{
  "name": "mod_vehicle_height",
  "value": "3.8"
}

Removing of Existing Vehicle Attributes

Sometimes it may be necessary to remove an existing vehicle attribute from a road segment. Let's say there is a bridge with a weight limit. You want to calculate a route for a fire truck that is heavier than this limit, but is still allowed to cross the bridge in case of an emergency.

To disable the limit, you must first query the vehicle attributes at this point. The endpoint [GET] /mapdata/vehicleattributes/geojson/{from}/{to} returns all road segments with vehicle attributes in a bounding box as a GeoJSON document to help you show them on a map.

For example, there is a weight limit of 3.5 tons at the coordinate 50.694529, 7.125839. The query

curl -X "GET" "https://api.maptrip.de/v1/mapdata/vehicleattributes/geojson/50.695154%2C%207.12397/50.693666%2C%207.1276732?provider=TomTom" -H "accept: application/geo+json" -H "Authorization: Bearer <token>"

returns this GeoJSON document:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [
            7.125608,
            50.69467
          ],
          [
            7.126784,
            50.693953
          ]
        ]
      },
      "properties": {
        "openlr": "CwURLSQMrzPMAgB2/7gzHA==",
        "mod_vehicle_total_weight": "3500"
      }
    }
  ]
}

To remove this weight limit from the map data, you have to create a detour segment from these coordinates and OpenLR code. Use the attributes returned by [GET] /detour/attribute/removedvehicleattributes for this new segment:

{
  "coordinates": [
    {
      "lat": 50.69467,
      "lon": 7.125608
    },
    {
      "lat": 50.693953,
      "lon": 7.126784
    }
  ],
  "openlr": "CwURLSQMrzPMAgB2/7gzHA==",
  "attributes": [
    {
      "name": "removed_vehicle_attributes",
      "value": "true"
    }
  ]
}

See Create a Segment for an example of how to add segments.

Important

This attribute removes all vehicle attributes from the segment in the map data. To modify existing attributes, you don't have to remove them first. Just get the attribute for the new value as shown in Vehicle Attributes and use this instead.

Time Domains

If you do not want to change road segments permanently, but only at certain times, you can use Time Domains.

  • To permanently change a road segment, do not specify Time Domains at all
  • To change a road between two dates, use [GET] /detour/attribute/timedomain/start and [GET] /detour/attribute/timedomain/end to specify the start and end dates (e.g. for a roadwork)
  • To change a road daily for certain times, use [GET] /detour/attribute/timedomain/daily to specify the hours (e.g. due to heavy traffic)
  • To change a road on a weekly basis for certain times (or all day), use [GET] /detour/attribute/timedomain/weekly to specify the week days and hours
  • To change a road on a monthly basis for certain times (or all day), use [GET] /detour/attribute/timedomain/monthly to specify the days of month and hours

The following attributes can be used for this purpose:

  • [GET] /detour/attribute/timedomain/start: Specifies that the other attributes are valid only after this date
  • [GET] /detour/attribute/timedomain/end: Specifies that the other attributes are valid only before this date
  • [GET] /detour/attribute/timedomain/daily: Limits the validity of the other attributes on a daily basis
  • [GET] /detour/attribute/timedomain/weekly: Limits the validity of the other attributes on a weekly basis
  • [GET] /detour/attribute/timedomain/monthly: Limits the validity of the other attributes on a monthly basis

Important

If you use time domains for Detour segments, make sure you add a start time for your route calculations. Routing requests without start time are calculated with all segments, whether they have a time domain or not.

Example: Time Span

Imagine there is are road works that makes a road segment impassable for the range of a few weeks, say for every day from July 30 to August 15, 2022.

You can specify these dates as ISO 8601 strings to the endpoints [GET] /detour/attribute/timedomain/start and [GET] /detour/attribute/timedomain/end: (UTC times were used for this example, but you can specify an offset for a local time zone instead).

Start:

curl -X GET "https://api.maptrip.de/v1/detour/attribute/timedomain/start?date=2022-07-30T00%3A00%3A00Z" -H "accept: application/json" -H "Authorization: Bearer <token>"

End:

curl -X GET "https://api.maptrip.de/v1/detour/attribute/timedomain/end?date=2022-08-15T23%3A59%3A59Z" -H "accept: application/json" -H "Authorization: Bearer <token>"

Example: Daily Time Span

Let's say you want to avoid a road at certain times every day because of the high traffic volume, e.g. every day from 4 to 6 pm (local time).

In this case use the endpoint [GET] /detour/attribute/timedomain/daily and use the parameter time to set the time as HH:mm-HH:mm (local time):

curl -X GET "https://api.maptrip.de/v1/detour/attribute/timedomain/daily?time=16%3A00-18%3A00" -H "accept: application/json" -H "Authorization: Bearer <token>"

Example: On a Weekly Basis

The endpoint [GET] /detour/attribute/timedomain/weekly allows to use rules on a weekly basis. You can provide a list of days of the week and optionally a time range per day.

This example changes the attributes of a segment on weekends all day:

curl -X GET "https://api.maptrip.de/v1/detour/attribute/timedomain/weekly?daysofweek=Saturday%2CSunday" -H "accept: application/json" -H "Authorization: Bearer <token>"

This example changes the attributes of a segment on weekends from 4 to 6 pm (local time):

curl -X GET "https://api.maptrip.de/v1/detour/attribute/timedomain/weekly?daysofweek=Saturday%2CSunday&time=17%3A00-19%3A00" -H "accept: application/json" -H "Authorization: Bearer <token>"

Example: On a Monthly Basis

The endpoint [GET] /detour/attribute/timedomain/monthly allows to use rules on a monthly basis. You can provide a list of days of the month and optionally a time range per day.

This example changes the attributes of a segment on every 7th and 21st of a month:

curl -X GET "https://api.maptrip.de/v1/detour/attribute/timedomain/monthly?daysofmonth=7%2C21" -H "accept: application/json" -H "Authorization: Bearer <token>"

This example changes the attributes of a segment on every 7th and 21st of a month from 4 to 6 pm (local time):

curl -X GET "https://api.maptrip.de/v1/detour/attribute/timedomain/monthly?daysofmonth=7%2C21&time=16%3A00-18%3A00" -H "accept: application/json" -H "Authorization: Bearer <token>"

Delete Existing Roads

The endpoint [GET] /detour/attribute/deleteroad returns attributes which delete a road from the map data. Adding these to a road segment has two effects:

  • The segment is no longer user for route calculation in the MapTrip Server API and MapTrip when this Detour file is used
  • The road is no longer visible in the Map in the Detour Editor and MapTrip when this Detour file is used

Important

This endpoint can only be used to delete existing roads from the map data. To delete newly created roads via Detour, see Delete a Road. To delete normal segments via Detour, see Deleting Detour Segments.

Validity

Validity attributes can be used to fine-tune your Detour changes for emergency routing and normal routing. They define whether the changes to this segment are considered for a route (either an emergency route or a normal route) or not.

Use the endpoint [GET] /detour/attribute/validity to query a validity attribute. The endpoint has three parameters: emergencyRouting defines the behavior for emergency routes in general (outside of the emergency radius), and withinEmergencyRadius especially around the destination (i.e. in the emergency radius). The third parameter defaultRouting can be used to define the behavior for normal, non-emergency routes.

All three parameters can be set to true to consider the segment changes or false to ignore them. When the parameters are not set a default behavior is used.

Let's have a look at an example: When you add a bidirectional block attribute to a road segment, by default the road is blocked for normal routes, but open for emergency routes. This behavior is correct for most situations, but imagine the road is completely closed because of roadworks. In this case, even an emergency vehicle can not pass during an emergency. Therefore, you should add an attribute to the road segment that closes the road for emergency routes as well:

curl -X GET "https://api.maptrip.de/v1/detour/attribute/validity?emergencyRouting=true&withinEmergencyRadius=true&defaultRouting=true" -H "accept: application/json" -H "Authorization: Bearer <token>"

Other Attributes

[GET] /detour/attribute/description can be used to add a description to a road segment which contains the street name or an explanation why this segment was changed. This description will be shown in the Detour Editor.

[GET] /detour/attribute/road is use to Create new Roads.