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.

Resource /v8/maps/list.html lists customer's private maps, /v8/maps/layers/list.json lists the layers of a map.

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.

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.

https://routematching.hereapi.com/v8/maps/overlays/upload?map_name=OVERLAYEXAMPLE1
&overlay_spec=[
  { "op":"override",
    "shape":[[50.10765,8.68774],[50.10914,8.68771]],
    "layer":"LINK_ATTRIBUTE_FCN",
    "data":{"VEHICLE_TYPES":"0"}
  },
  { "op":"create",
    "shape":[[50.10937,8.68422],[50.10807,8.68525],[50.10737,8.68387]],
    "data":{"NAMES":"ENGBNDemo Road"}
  },
  { "op":"override",
    "shape":[[50.10937,8.68422],[50.10807,8.68525],[50.10737,8.68387]],
    "layer":"TRUCK_RESTR_FCN",
    "data":{"VEHICLE_TYPES":"truck", "WEIGHT_RESTRICTION":"3300"}
  }
]
&storage=readonly
&app_id=YOUR_APP_ID&app_code=YOUR_APP_CODE

Note: If your HTTP client doesn't URL-escape the brackets then you have to do it before sending.

More examples in the Support Demo Suite:

You can quickly try out overlays on Support Demo Suite.

Overlay description format

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.

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.

Example: Set a 2 meter height limit between 0 and 7am on link 833297602 (Germany, Schwanheim, Rheinlandstraße, South of the roundabout)

[{"op":"restrict","shape":[[50.08562,8.58945],[50.08447,8.58847]],"type":"access","bidirectional":"true","data":{"HEIGHT_RESTRICTION":"200","DATE_TIMES":"1:N:N:XXXXXXX ::0000:0700"}}]

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.
• data – like in the Overlay Override Object

Example 1: Close all roads in this area.

{"op":"areaoverride", "shape":[[50.09211,8.6143],[50.09234,8.61902],[50.08994,8.61958],[50.09002,8.61447]], "layer":"LINK_ATTRIBUTE_FC3", "data":{"VEHICLE_TYPES":"0"}}

Example2: Speed up all non-pedestrian streets in this area:

{"op":"areaoverride", "shape":[[50.09211,8.6143],[50.09234,8.61902],[50.08994,8.61958],[50.09002,8.61447]], "layer":"LINK_ATTRIBUTE_FCN", "data":{"VEHICLE_TYPES":"1007", "SPEED_CATEGORY":"2"}}

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.