Custom Route Extension API Developer's Guide

Overlay Description Format

Overlay maps are described in a JSON formatted file. When you submit an overlay file, they are compiled into Platform Data Extension API layers and stored as a separate map with the layers containing the map changes.

Contents of an Overlay Description File

An overlay description file consists of a JSON array with JSON objects. Each JSON object describes a single map modification operation.

The op field is a mandatory field that specifies the type of operation:
  • op : create – Creates a new road link
  • op : override – Changes the attribute values of an existing link attribute (such as allowed vehicle types), or add a restriction (condition) to a link (like a truck weight limit).
  • op : restrict – Adds a link access or turn restriction (incl. truck specific like width limit) or overwrites an existing one for the link.

The other fields of an operation are specified below.

Note: Additional truck restrictions can only make access more restricted, but also override existing ones to relax or reomve them. To remove e.g. a truck weight restriction, overwrite the exitinsg one with a 100 tons limit.

Overlay Create Object

You can create a new link between two existing links. Currently, you can specify the link geometry and their corresponding attributes. All other link attributes are copied from an existing neighboring link. The existing links are always cut at the point where the new link is inserted.

A new link can either connect on each end to existing (or other new) links, or one end can stay unconnected (dead end).
  • shape – An array of shape points where each shape point is an array of two elements, latitude and longitude, in WGS-84 degree

    Currently, the first and last point must each fit within 5 meters tolerance onto existing links. These points must not both end up on the same link.

  • layer – The Platform Data Extension API layer, in which to insert the link or new restrictions

    Currently, only the LINK_ATTRIBUTE_FCN layer is supported.

  • data – The map of attribute/value pairs

    Currently only VEHICLE_TYPE and TRAVEL_DIRECTION are supported. For more information on Layers, Indexes, and Attributes see the Platform Data Extension API documentation.

    TRAVEL_DIRECTION can be defined using B/F/T (bi-directional, driving from reference node, driving towards reference node) or using BOTH/FORWARD/BACKWARD (bi-directional, driving in sequence order of the shape points, driving against their sequence order).

Overlay Override Object

You can modify attributes of an existing link, or attributes in a sequence of existing links. Currently, the following attributes are supported:
  • shape – An array of shape points where each shape point is an array of two elements, latitude and longitude, in WGS-84 degree. The geometry must be an approximate match of the existing link's geometry; shape points can be ommitted. If the geometry denotes a path of several connected links in the map, then the attributes of all these links are changed.
  • layer – The Platform Data Extension API layer in which the link attributes need to be changed. Currently, the LINK_ATTRIBUTE_FCN and TRUCK_RESTR_FCN layers are supported.
  • data – The map of attribute/value pairs. Currently, for layer LINK_ATTRIBUTE_FCN, only VEHICLE_TYPE and TRAVEL_DIRECTION are supported. For layer TRUCK_RESTR_FCN, the attributes VEHICLE_TYPES, WEIGHT_RESTRICTION, HEIGHT_RESTRICTION, LENGTH_RESTRICTION, WIDTH_RESTRICTION, MAX_WEIGHT_PER_AXLE, NUMBER_OF_AXLES, KPRA_LENGTH, HAZARDOUS_MATERIAL_TYPE, HAZMAT_PERMIT_REQUIRED are supported. For more information on Layers, Indexes, and Attributes see the Platform Data Extension API documentation.

Overlay Restrict Object

You can add or modify access/turn restrictions on an existing link. Currently, the following attributes are supported:
  • shape – An array of shape points where each shape point is an array of two elements, latitude and longitude, in WGS-84 degree. The geometry must be an approximate match of the existing link's geometry; shape points can be ommitted. If the geometry denotes a path of several connected links in the map, then the restrictions extends as a path over all these links.
  • data – The map of attribute/value pairs. Currently, the attributes VEHICLE_TYPE, TRAVEL_DIRECTION, WEIGHT_RESTRICTION, HEIGHT_RESTRICTION, LENGTH_RESTRICTION, WIDTH_RESTRICTION, MAX_WEIGHT_PER_AXLE, NUMBER_OF_AXLES, KPRA_LENGTH, HAZARDOUS_MATERIAL_TYPE and HAZMAT_PERMIT_REQUIRED are supported. For more information on Layers, Indexes, and Attributes see the Platform Data Extension API documentation.
  • type – Can be access or rdm (for restricted driving maneuvre).
  • bidirectional – Otopnal parameter for access restrictions. Specifies that the restriction doesn't only apply into the direction defined by the shape, but in both driving directions.
Note: The according layers (TURN_RESTR_FC* or TRUCK_RESTR_FC*) are determined automatically.