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.