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 prohibiting roads and reducing the driving speed is possible. It is planned to add additional possibilities like opening closed roads or modifying weight or height restrictions 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.

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 or a polyline. For a single point the road closest to this point will be chosen. Several points will be considered as a polyline and all roads intersected by this polyline will be chosen. Please note that ferries will not be selected.

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 or polyline 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 your point or polyline.

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.
attributes
- This parameter defines the attributes assigned to each of the selected roads.
- With prohibited the roads will not be used in route calculation.
- With relativeSpeed the driving speed on the roads will be reduced to this percent value.
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.

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"
        }
    ]
}