Customer's maps and custom map changes - bring your own data
Customers can create their own private maps containing changes and additions to the road network. These maps are "overlays" to the HERE map network and change HERE Route Matching v8's routing / route matching behavior. Overlay maps can add additional roads, modify road attributes (like access permissions, one way direction, weight restrictions, driven speed...) or block roads.
Customers use overlay maps to enable routing / route matching into and within their private facility roads, up to the individual loading docks, or to block / allow / prefer certain roads for their fleets.
Upload custom maps
Customers can upload/update their road overlay maps in "overlay" format. Private maps can be uploaded/updated via HERE Route Matching v8 REST calls.
Resource /v8/maps/overlays/upload uploads an overlay that changes a road access permission and adds a road. Please note that uploads should use POST requests.
When you provide modified maps via overlays, HERE Route Matching v8 compiles your changes into routable binary map format. Route Matching uses these layers on top of the HERE map layers.
Note
Although overlay maps are stored among customer's private maps in the same format, it is highly recommended to create, modify, and delete them using the "v8/maps/overlays/upload" resource.
Overlay maps and layers
As a customer, you can create, use, and update multiple overlay maps. For example, one overlay map with changes for waste collection vehicles, and another map with changes for oversize transports.
In a routing / route matching request, one of these overlay maps can be specified and will override/augment the map attributes and topology.
An overlay map contains multiple additions and overrides for individual road links.
Additions are new road links. Overrides are either changes to road link attributes (like speed, permitted vehicle type or driving direction), or additional access/turn restrictions on road links (like truck weight limit or truck length dependent turn restriction).
Overlay maps are organized in thematic layers that correspond to the HERE Route Matching v8 routing layers. Routing mainly relies on the HERE Route Matching v8 layers LINK_FCN, ROAD_GEOM_FCN, LINK_ATTRIBUTE_FCN, TURN_RESTR_FCN and TRUCK_RESTR_FCN.
Examples
Close to the Alte Bruecke in Frankfurt, Germany and insert a new bridge to its West. Limit the new bridge to 3.3 tons.
Overlay maps are described in a JSON formatted file. When you submit an overlay file, they are compiled into HERE Route Matching v8 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.
op : areaoverride - Changes the attribute values of all existing links within this polygonal area
The other fields of an operation are specified below.
Note
Additional truck restrictions can only make access more restricted, but one can also override existing ones to relax or remove them. To remove a restriction such as a truck weight, overwrite the existing 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 degrees. 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 HERE Route Matching v8 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 HERE Route Matching v8 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 omitted. If the geometry denotes a path of several connected links in the map, then the attributes of all these links are changed.
layer – The HERE Route Matching v8 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 HERE Route Matching v8 documentation.
VEHICLE_TYPES can also specify whether through traffic is allowed or not.
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 omitted. 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 HERE Route Matching v8 documentation.
type – Can be 'access', 'turn restriction' or 'transport rdm' (restricted driving maneuver for truck weight, height, length...).
bidirectional – Optional parameter for access restrictions. 'true' makes the restriction apply into both driving directions. Default is 'false', restriction applies into the direction defined by the shape point order.
Note
The relevant layers (TURN_RESTR_FC* or TRUCK_RESTR_FC*) are determined automatically.
Example: Set a 2 meter height limit between 0 and 7am on link 833297602 (Germany, Schwanheim, Rheinlandstraße, South of the roundabout)
Custom turn restrictions can also be set: Define from-link, to-link, affected vehicle types and date/times,
For example [{"op":"restrict","shape":[[53.54742,9.99704],[53.54746,9.99765],[53.54999,9.99999]], "type":"7", "data":{"TIME_OVERRIDE":"0","VEHICLE_TYPES":"1","RDM_TYPE":"1"}}]
Modify multiply digitized roads and one ways
The overlay geometry can optionally be matched onto both directions of multiply digitized roads. Use request parameters "multidigitized_handling" to switch it on for the whole overlay.json file. Use operation parameter "multidigitizedHandling" to switch it on for individual road sections.
To modify or block one ways, the geometry points should advance in the allowed direction of travel, because map matching tries to avoid matching geometry onto roads resulting in illegal access/maneuvers. If this is not possible or not known, use parameter "bidirectional" to match onto roads regardless of the travel direction.
Bulk-modify all links within an area
You can modify the attributes of all existing links that are completely within the given polygon. 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 build a clockwise polygon (without holes, not self-intersecting, no degenerated zero size parts).
layer – The HERE Route Matching v8 layer in which the link attributes need to be changed. Currently only the LINK_ATTRIBUTE_FCN layers are supported.
One overlay operation can include at most 500 links. Larger operations can be split geometrically or by functional class.
Handle existing roads inside your facility
Often (part of) the private roads are already present in HERE's road network. Per default, the custom geometry connects to them. However, if the custom geometry refines and supersedes the present road network, then use parameter &private_link_handling=DROPEXISTING to block (and not connect to) any existing private road links, which are within the vicinity of the new custom geometries. Another options is to keep the existing private roads but not connect to them.
Avoid or prefer certain road links
Custom routing can consider user specific penalties or bonus for road links. If certain streets are cumbersome or well suited for certain vehicle types of a fleet, a custom road overlay can define individual penalties or bonus for using these streets.
For example [{"op":"restrict","shape":[[53.54742,9.99704],[53.54746,9.99765]], "type":"preferred", "data":{"VEHICLE_TYPES":"145","PREFERRED_ROUTE_TYPE":"201","ENTRY_PENALTY":-1,"DRIVE_PENALTY":-0.1}}]
Negative penalty values make routing prefer certain links. Assigning too high penalty or bonus values can impact response time. A penalty/bonus consists of an ENTRY_PENALTY - a fixed (seconds) value to enter the (stretch of) link(s) and/or a DRIVE_PENALTY slow-down factor to traverse the link.
The "type:preferred" and PREFERRED_ROUTE_TYPE":201 are mandatory prefer or avoid road links, because they create access conditions "preferred route type" (type 27) in the map.
Define your own restriction types (like virtual traffic signs)
You can set restrictions with custom values (vectors of values), e.g. on this road link only our at least 50kph enabled class 3+ cars are allowed. Or block certain roads for your custom van/truck/trailer categories/properties or ground clearance.
Use [{"op":"restrict","shape": ... { ..., "CUSTOM_RESTRICTIONS":"0:100,1:90,2:60", ...} on a (stretch of) link(s) to permit only cars with property#0 up to 100, property#1 up to 90 and property#2 up to 60. In routing calls specify &customRestrLimit=0:40,2:4 for a car that has property#0 value 40 and property#2 value 4 (and property#1 undefined).
Vehicle types
Access restrictions apply to certain vehicle types. The vehicle types can be specified by name (comma separated list) like "truck,bus,car" or as a bitmask (sum) of the corresponding numeric vehicle types. The map documentation shows the supported vehicle types in section VEHICLE_TYPES.