Custom Routes

When you provide modified maps via overlays, Fleet Telematics API compiles your changes into routable binary map format. Routing 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 request, one of these overlay maps can be specified and will override 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 Fleet Telematics API routing layers. Routing mainly relies on the Fleet Telematics API 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.

http://fleet.ls.hereapi.com/2/overlays/upload.json?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"}
  },
]
&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.

Create the new bridge with a height and a weight restriction:

[{"op":"create","shape":[[50.10937,8.68422],[50.10807,8.68525],[50.10737,8.68387]],"data":{"NAMES":"ENGBNTestRoad"},
  "restrictions":[{"CONDITION_TYPE":"23","VEHICLE_TYPES":"truck,car","WEIGHT_RESTRICTION":"3500"},{"CONDITION_TYPE":"23","VEHICLE_TYPES":"truck,car","HEIGHT_RESTRICTION":"200"}]}]

Overlay Description Format

Overlay maps are described in a JSON formatted file. When you submit an overlay file, they are compiled into Fleet Telematics 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.
• 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 Fleet Telematics 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 Fleet Telematics API documentation.

• restrictions - list of truck or turn restrictions Each restriction has a CONDITION_TYPE (7 for turn restrictions, 23 for truck access restrictions, 26 for truck turn restrictions). Further supported attributes are VEHICLE_TYPES, WEIGHT_RESTRICTION, HEIGHT_RESTRICTION etc.

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 Fleet Telematics 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 Fleet Telematics 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 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 Fleet Telematics API 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"}}]

Modifying Multiply Digitized Roads and One Ways

The overlay geometry can optionally be matched onto both directions of mutliple 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 gemoetry onto roads resluting in illegal access/maneuvers. If this is not possible or not knowm, 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 comletely 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 selfintersecting, no degenerated zero size parts).
• layer – The Fleet Telematics API 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.

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).

Custom Vehicle Types

In addition to standard vehicle types like car or truck, you can also use custom vehicle types. The steps below describe this process:

• When you are modifying an overlay, override operations on the LINK_ATTRIBUTE_FCN layer can change the vehicle types that are allowed on this particular link. You can specify standard vehicle types like car or truck, and also custom vehicle types custom1, custom2, custom3, or custom4. Use a comma-separated list to add custom vehicles in addition to standard vehicles.
• For routing calls, the vehicle types custom1, custom2, custom3 or custom4 can be specified instead of, or in addition to (using a comma-separated list), car or truck. Then the Routing API only uses the links that are allowed for (any of) the specified vehicle type(s).
• If certain vehicles in your truck fleet are allowed to use certain links, but others are forbidden, then you can override the vehicle types of these links by allowing custom1, additionally. For routing calls, you can either specify mode=truck,custom1 so that the truck can use those links, or just specify mode=truck to get the normal behavior.