Custom Road Attributes

With custom road attributes you have the possibility to modify attributes of roads in the map data to your individual needs (e.g. to consider short-term roadworks on a daily used road and currently not available in the map data). Please note that such changes are relevant for routing and apply to all vehicle profiles. Therefore two steps are necessary: First create a scenario for one or more selected roads with the Data API and second use this scenario in the Routing API.

At the moment allowing/prohibiting roads, reducing the driving speed and modifying vehicle dimensions like weight or height is possible. It is planned to add additional possibilities at a later time. Generally speaking, custom road attributes that are assigned to the selected roads.

Try it in the corresponding showcase! Please note that you need an API key for this showcase as the scenarios are stored within your PTV Developer subscription of your myPTV account. Or learn how to model traffic restrictions related to the Paris 2024 Olympic Games with custom road attributes in the Olympic Games showcase.

Step 1: Create a custom road attribute scenario

A custom road attribute scenario stores one or more roads to be attributed. For this it contains several information like a user-defined name and of course the roads (or more exact the selection criteria of these roads) including the affected direction. Moreover, you can set a period during which the attributes of every road are valid or even mark the whole scenario simply as active or inactive. It is also possible to share the scenario with other users. Please refer to the API documentation for detailed information about the parameters.

To create a custom road attribute scenario we provide the method createCustomRoadAttributeScenario in the Data API. As input data you have to select roads, attribute them and finally create a scenario.

Select roads

To select roads you can submit a point, a polyline or a polygon. For a single point the road closest to this point will be selected. Several points with different start and end point will be considered as a polyline and all roads intersected by this polyline will be selected. Several points where the start and end point are the same will be considered as a polygon and all roads within this polyline will be selected. Please note that ferries will not be selected.

The number of roads, that can be selected with a polyline or a polygon, is limited to 5,000 roads. If a selection covers too many roads, the response will contain an error and you need to reduce the selection, so fewer roads are covered.

As you need for the scenario creation the selection criteria of the roads and not the roads itself, you can check your selection determined by your point, polyline or polygon with the method getRoads. The polylines of the roads can be returned in two different formats, requested by the query parameter polylineFormat.

GEO_JSON (https://geojson.org/)
GOOGLE_ENCODED_POLYLINE (https://developers.google.com/maps/documentation/utilities/polylinealgorithm)

This example shows how to request the roads, selected by a point.

https://api.myptv.com/data/v1/roads?points=48.9073824286,8.32815170288

As response you will get the polyline of the closest road to the submitted point.

Attribute roads

Within the parameter roadsToBeAttributed you specify the selected roads in the parameter points and the corresponding attributes in the parameter attributes. Both parameters are required. The parameters direction, validity and description are optional.

points
- This parameter defines the roads to be attributed by using the selection criteria as described above. The same limitations for the number of roads apply.
attributes
- This parameter defines the attributes assigned to each of the selected roads.
- With prohibited the roads will not be used in route calculation. Mutually exclusive with allowed.
- With allowed the roads will be used in route calculation. This includes one-way roads depending on direction, as well as restrictions from vehicle dimensions (weight, height, etc.) and general restrictions for the used vehicle such as environmental zones. Traffic situations cannot be lifted using allowed. Setting the same road as allowed and prohibited in a different selector of the same scenario or even in a different scenario will result in the road being treated as prohibited. Mutually exclusive with prohibited.
- With relativeSpeed the driving speed on the roads will be reduced to this percent value.
- With weightLimit the roads will be restricted so that they can be used only by vehicles with a weight less or equal to this limit. If the map already contains a weight limit and this is greater than that, it will be ignored. That means, it is not possible to relax or remove an existing restriction.
- With heightLimit the roads will be restricted so that they can be used only by vehicles with a height less or equal to this limit. If the map already contains a height limit and this is greater than that, it will be ignored. That means, it is not possible to relax or remove an existing restriction.
- With widthLimit the roads will be restricted so that they can be used only by vehicles with a width less or equal to this limit. If the map already contains a width limit and this is greater than that, it will be ignored. That means, it is not possible to relax or remove an existing restriction.
direction
- This parameter defines the affected direction of the road (e.g. only in one direction or in both directions).
validity
- This parameter defines the periods during which the attributes are valid.
- You can use time intervals with an explicit start and end date or alternatively a weekly schedule (e.g. every Sunday from 8:00 to 20:00)
description
- This parameter defines a description of the modifications in the attributed roads which is useful to refer in an application.

The total number of roads covered by all roadsToBeAttributed within one scenario must not exceed 25,000 roads. If this limit is exceeded, the response will contain an error and you need to reduce the selections so fewer roads are covered.

Create a scenario

To create a minimal road attributes scenario, at least the following parameters are required.

{
    "roadsToBeAttributed": [
        {
            "points": "48.8973714, 8.2472938",
            "attributes": {
                "prohibited": true
            }
        }
    ]
}

As response a scenario object including its id will be returned.

Besides the creation you also find the other typical CRUD methods in the Data API to manage the scenarios (getAllCustomRoadAttributeScenarios, getCustomRoadAttributeScenario, updateCustomRoadAttributeScenario, deleteCustomRoadAttributeScenario).

Step 2: Use a custom road attribute scenario

To use your custom road attribute scenario with our Routing API you just have to submit the scenario with the parameter customRoadAttributeScenarios in the routing options. Here is an example routing request using a custom road attributes scenario.

https://api.myptv.com/routing/v1/routes?waypoints=48.89516,8.24305&waypoints=48.89995,8.24879&options[customRoadAttributeScenarios]=10005f72-0633-42a1-818d-a281f1a90334

Own scenarios can also be set via their names. Shared scenarios, used with a different user, have to be requested with their ids.

If you use a custom road attributes scenario together with a routing request based on a routeId, you will get a violation when the route passes a road which was prohibited by your scenario.

Map update

After a new map release for the PTV Developer APIs, your custom road attributes scenarios will be ported to the new map. In few cases it may occur that a road can not be matched. Those roads will be marked with the parameter unmatchedAfterMapUpdate: true.

Example request to get your custom roads attribute scenario:

GET https://api.dev.myptv.com/data/v1/road-attributes/YourScenarioId?results=POLYLINES&apiKey=YourApiKey

Example response with an unmatched road:

    "id": "YourScenarioId",
    "name": "TestUnmatched",
    "roadsToBeAttributed": [
        {
            "points": "48.96851260249437,8.31032610223329,48.9682631091722,8.310841584428147",
            "polylines": [
                "{\"type\":\"LineString\",\"coordinates\":[[8.309377699700002,48.967294035],[8.3113673496,48.968912542]]}",
                "{\"type\":\"LineString\",\"coordinates\":[[8.3111943366,48.968940936],[8.3100697518,48.968032308]]}"
            ],
            "direction": "BOTH",
            "attributes": {
                "prohibited": true
            },
            "unmatchedAfterMapUpdate": true
        },
        ...

To fix the road attributes scenario, you have to check the polylines for each such set of roads.

If they still represent the roads you want to attribute, you just have to remove the unmatchedAfterUpdate parameter.
If they do not represent the roads you want to attribute, you have to adjust the points which select the roads.
If they are not relevant, anymore, you have to remove them.

After that you have to send an update request with your complete scenario.

In case of a routing request with a scenario which has an unmatched road, you will get a warning in your routing response:

{
    "distance": 236265,
    "travelTime": 9039,
    "trafficDelay": 165,
    "violated": false,
    "warnings": [
        {
            "description": "At least one of the scenarios given in options[customRoadAttributeScenarios] could not be fully considered in the route calculation after a map update, i.e. some road attributes may have been ignored.",
            "warningCode": "ROUTING_ROADATTRIBUTES_MAYBE_IGNORED"
        }
    ]
}