Maps and Layers

Maps

Fleet Telematics API is based on and offers simple on access to all HERE map data and customers' private map data. Therefore the Fleet Telematics API works with multiple maps, e.g.:

Fleet Telematics API uses HERE maps and customers' maps. A map is a collection of layers. A layer contains map objects with geometry and attribution. A layer's content is cut into tiles, for efficient search, map display, routing, map matching and driver warnings.

Resource https://fleet.ls.hereapi.com/1/doc/maps.html?apikey=YOUR_API_KEY shows the available maps. The core map content is divided into regional maps, but can always be used as a single, global map. Other content is delivered in dedicated - mostly worldwide - maps.

Layers

Fleet Telematics API groups HERE map data into thematical layers. Each layer contains rows (map objects), like road segments, points of interest, river polygons - their geometry and attributes (columns). Some layers just extend the objects of another layer by additoinal atributes, like the speed limits for a road segment layer. Layers without geometry are called "attribute" layers, as opposed to "geometry" layers.

Layers are made for certain use cases:

• layers that display warnings to the driver
• layers that provide Junction View guidance
• layers that enable fuel efficient driving
• layers that enable safe driving
• layers that provide access to polygons that describe the hierarchy of administrative regions

Use the appropriate layer to request only the relevant data to minimize data transfer. Since the layers offered by the Fleet Telematics API change often, check the currently supported layers with the resource Layers.

Resource https://fleet.ls.hereapi.com/1/doc/layer.html?region=WEU&layer=SPEED_LIMITS_FC2&apikey=YOUR_API_KEY shows the attributes (columns) of a speed limit layer.

Resource https://fleet.ls.hereapi.com/1/tile.json?region=WEU&layer=SPEED_LIMITS_FC2&level=10&tilex=934&tiley=669&apikey=YOUR_API_KEY shows a tile content of a speed limit layer. Alternatively, it is shown in simple text format, as follows: https://fleet.ls.hereapi.com/1/tile.txt?region=WEU&layer=SPEED_LIMITS_FC2&level=10&tilex=934&tiley=669&apikey=YOUR_API_KEY.

Example speed limit layer tile content:

A typical example for using layers is when you need to retrieve information along a particular route. A route usually starts on smaller roads, follows bigger roads, then stays on motorway-like roads for the main part of the journey, and finally returns onto smaller roads when approaching the destination. Retrieving all the information about smaller roads along the whole route can result in an overwhelming amount of data transfer. Therefore, road link related layers are split into five layers each corresponding to the functional classes used in HERE maps. To keep the data processing simple, each layer consists of a single flat table with simple records in numbers or text strings represented as attribute key/value pairs.

To reduce the volume of data transferred, some columns are denormalized or encoded. Denormalization is done by storing a list of comma-separated values in a column. Encoding is done by using abbreviations or numbers to represent static string values, bit mask for a vehicle's type, and so on. For example, each geometry is delivered in a single column per coordinate (x, y, z-level columns). Each coordinate is a comma-separated list of integer values in 1E-5 WGS degrees (or 1E-7 for ADAS accuracy). The first value is absolute. Each subsequent value is relative to the previous value; a zero (0) value is reduced to an empty string.

The following tiled layers are available:

• ADAS_ATTRIB_FC1...5 Curvature, height, slope, inside-builtup
• ADMIN_PLACE_0/1/2/8/9 Administrative area info
• ADMIN_POLY_0/1/2/8/9 Administrative area geometry
• BASIC_HEIGHT_FC1...5 Link height
• BUILDING Building type, height, footprint geometry
• CARTO_LINE_DO0/1/2/8/9 Cartographic line type, name, geometry
• CARTO_POLY_DO0/1/2/8/9 Cartographic polygon type, name, geometry
• CARTO_POLY_OCEAN Cartographic ocean polygon name, geometry
• CARTO_POLY_RIVER_DO0/1/2/8/9 Cartographic river polygon type, name, geometry
• CARTO_POLY_TOLL_HAZ Cartographic toll zone and hazardous area polygon name, geometry
• CENSUS_0/1/2/8/9 Basic census area info
• CEN_* Country-specific census info
• CITY_POI_0/1/2/8/9 City center POI info, location
• DISTANCE_MARKERS_FC1...5 Distance marker info, location
• DTM_HEIGHT Digital terrain model grid height
• EVCHARGING_POI Electric vehicle charging station info, location
• FUELSTATION_POI gasoline, diesel, and EV charging offerings
• JUNCTION_VIEW 2D junction info, location, reference to image
• LANE_CONN_FC1...5 Lane level guidance link connectivity info
• LINK_ATTRIBUTE2_FC1...5 Advanced link info for routing, map display
• LINK_ATTRIBUTE_FC1...5 Basic link info for routing, map display
• LINK_FC1...5 Link connectivity info for routing, guidance
• LINK_TMC_FC1...5 LINK TMC for live traffic processing
• MICROPOINT_ADDRESS Address location, info with house number building unit and level for map display
• NATURAL_GUIDANCE Natural guidance info
• POINT_ADDRESS Address location, info with house number for map display
• POI_BIG Point of interest info, location for map display
• POI_BIGGER Point of interest type, info, location for map display
• POI_SMALL Point of interest type, info, location for map display
• POI_SMALLER Point of interest type, info, location for map display
• PSTLCB_GEN Postal code boundary generalized geometry
• PSTLCB_MP Postal code boundary mid point location
• PSTLCB_UNGEN Postal code boundary geometry
• PSTLCMIDP Postal code area mid point location for map display
• PUBLIC_TRANSPORT_POI Public transport stop locations, like bus stops and subway stations for map display
• ROAD_ADMIN_FC1...5 Road link's administrative hierarchy, postal code
• ROAD_ADMIN_NAMES_FC1...5 Road link's official names of the admin hierarchy (builtup, city, district, state, country).
• ROAD_GEOM_FC1...5 Road link info, geometry for map display
• ROAD_NAME_FC1...5 Road link name
• ROAD_OVERVIEW Generalized rad geometry for map display
• ROAD_ROUGHNESS_FC1...5 Classification of the road surface roughness for driver warning
• ROUNDABOUT_FC1...5 Roundabout info
• ROUTING_FC1...5 Compact representation of link info, connectivity, conditions for routing
• SAFETY_ALERTS Locations of accident spots and speed cameras, for driver warning
• SIGNPOST Direction sign info
• SPEED_LIMITS_COND_FC1...5 Conditional speed limit info
• SPEED_LIMITS_FC1...5 Car speed limit info
• SPEED_LIMITS_VAR_FC1...5 Variable speed sign info
• STAB_TOPO_ID_FC1...5 maps between Link IDs and their corresponding Stable Topology IDs with offset.
• TOLLCOST_FC1...5 Road toll cost info for toll calculation/optimization
• TOLL_BOOTH_FC1...5 Toll booth info for toll calculation/optimization
• TOLL_LINK_FC1...5 Road link toll info for toll calculation/optimization
• TRAFFIC_PATTERN_FC1...5 Typical link speed per time of day and weekday
• TRAFFIC_SIGN_FC1...5 Traffic sign info for driver alerts
• TRAFFIC_SPEED_RECORD_FC1...5 Live traffic info recorded from the last days, at a 15 minute resolution
• TRUCK POI Truck-specific rest area and restaurant info
• TRUCK_RESTR_FC1...5 Truck restriction info for routing
• TRUCK_SPEED_LIMITS_FC1...5 Truck speed limit info
• TURN_RESTR_FC1...5 Turn restriction info
• VIRT_CONN Virtual connection link info, geometry for routing, map display

The following non-tiled (static) layers are available:

• ADMIN_REGULATIONS Administrative level regulations, time zones
• ADMIN_TRUCK_RESTR Administrative level truck restrictions
• COUNTRY Country info
• TC_ADMIN Administrative level road toll info
• TC_SYSTEM Toll operator info
• TC_TOLLSYS_NAMES Toll operator names
• TC_VEH_TYPES Toll vehicle type info
• TRAFFIC_PATTERN Traffic speed curves

For more details and licensing info, see the /doc/layers.html service documentation.

Resource https://fleet.ls.hereapi.com/1/doc/layers.html?region=WEU&apikey=YOUR_API_KEY shows the available core map layers.

Some layers contain non-spatial data (independent of locations), e.g. toll vehicle type definitions. Fleet Telematics API refers to these attributes as "static" content, stored in "static" layers. Applications always retrieve the full layer content (not a tile, no searches).

Another example: The records in the (tiled) Traffic Pattern layers contain a PATTERN_ID. In adition there is a static layer containing the full specification for each PATTERN_ID.

File References

While the flat text file format is suitable for HERE core map data, it is not suitable for pixel images like Junction Views. For this type of map content, the layers contain a file path.

To retrieve the content itself through the Fleet Telematics API, you can use the path parameter after the layer parameter. The path information is published for tiled or static layers, if they can be enhanced with external file data, such as Junction View SVGs.

Resource https://pde.cit.api.here.com/1/file.bin?layer=JUNCTION_VIEW&path=16x9/SR_US_720476088.svg&apikey=YOUR_API_KEY retrieves a junction view image.

Indexes

Some layers offer a search index on certain attributes for efficient search. E.g. map data attributes are also indexed which allows you to request which tiles contain specific values in attribute key/value pairs. Resource https://fleet.ls.hereapi.com/1/doc/indexes.html?region=WEU&apikey=YOUR_API_KEY shows the available indexes in core map layers.

Use indexes if you don't know the spatial location of the map objects you're looking for. E.g. you know the Link ID or Admin Place ID. If you know the location then use tile.json or spatial search resources to retrieve the data.

The index.json resource tells in which tile(s) the requested object is so that it can be retrieved via tile.json.

Resource https://fleet.ls.hereapi.com/1/index.json?layer=ROAD_GEOM_FC3&attributes=LINK_ID&values=17339738%2C17339811&apikey=YOUR_API_KEY finds in which road geometry layer's tiles the link IDs 17339738 and 17339811 reside.

Tiles & Tile Sizes (Levels)

Each layer's data is cut into "rectangular" WGS84 degree tiles, for efficient access.

The size of (a region covered by a) map tile depends on layer's tile size "level". The lower the "level" number, the more area the tile covers. For example, tiles for level 2 cover a broader region than tiles for level 10.

As shown in below figure, tiling divides the world recursively into halves.

• Level 0 contains 2 x 1 tiles (East and West of Greenwich) and each tile comprises 180 x 180 degrees.
• Level 1 contains 4 x 2 tiles, where each of the 2 level 0 tiles are subdivided into 4 parts.
• On Level N, each tile comprises 180.0 / (2 level) degrees into each direction.

Each layer has a fixed tiling size (level). For road link based layers, the level is always "road functional class" + 8 E.g. the layer containing the functional class 2 (= roughly second level) roads has tiling level 10.

Layer tiling follows the Navigation Data Standard (NDS) tiling scheme.

A tile "owns" its lower and left borders, meaning that objects on those borders belong into this tile. Map objects on a tile's upper or right border belong to the respective neighbor tile. Still, for points, the tile also contains (a copy of) the points on its right/upper borders.

Polylines and polygons are cut at tile boundaries.

Hence, artificial points are created on the boundaries, and marked as such. These artificial points exist in both tiles with identical coordinates. Polygons that cut at tile borders are closed on each side. With this tiling schema, you can choose to do one of the following:

• Ignore the tiling and use the tiled fragments as separate map objects
• Remove the additional geometry and stitch tiled geometries back together
• Suppress the drawing of artificial tiling lines as polygon border lines

Pieces of a tiled geometry can be identified as belonging to each other if they have the same permanent IDs, such as link IDs or carto/face IDs.

Some layers do not cut the geometry into tile pieces, but copy the whole geometry of an object into each of the tiles it covers. This is described in the respective layers' documentation. For more information on layers, see Layers, Indexes, and Attributes.

Tiled links are represented as:

• Tile A - start node, shape point(s), artificial shape point
• Tile B - artificial shape point, shape point(s), end node

Artificial shapes are also represented as relative coordinate values that are relative to the previous shape point.

Which tile shall i request for map objects at coordinate "latitude", "longitude"?

Compute the tile ID that covers a given coordinate in a layer as follows:

          tile size = 180° / 2^level [degree]
          tileY = trunc((latitude  +  90°) / tile size)
          tileX = trunc((longitude + 180°) / tile size)

Map Object Identifiers

Each layer has one (or multiple) key attributes, called "identifier". For example, road segments are globally, uniquely and permanently identified by a Link ID.

HERE map object identifiers never change for an object. However, e.g. if a road segment is split, the parts get new (different) identifiers, and the old identifier is no longer used.

Use identifiers to combine a map object's across multiple layers. E.g. take the Link ID of the road geometry layer to identifier the according speed limit value in the speed limit layer.

The most heavily used identifier is the Link ID:

• A link is a piece of road with a fixed set of attributes. A link ends at an intersection, or when any of its attributes change, such as the speed limit.
• A link has a node at each of its ends. The lower left node (lower latitude, or if equal then lower longitude, or if equal then lower z-level) is called a Reference Node. The other node is called a Non-Reference Node. A node can connect two links to attribute changes along the road, or multiple links when there's an intersection.
• Each link is globally identified by a Link ID.

Map Regions

The HERE map is divided into the following regions:

• ANTARC – Antarctica
• APAC – Asia Pacific
• AUS – Australia
• EEU – Eastern Europe
• HKG – Hong Kong
• IND – India
• MEA – Middle East Africa
• NA – North America
• SAM – South America
• TWN – Taiwan
• WEU – Western Europe

Requests to the Fleet Telematics API can refer to one or more regions by using the region parameter. However, the region parameter is optional in most cases, except for when you use the doc/maps resource.

Map Releases

HERE releases its maps quarterly and weekly. By default, Fleet Telematics API delivers the latest available map release for each map region. But the API also offers older map releases on demand, which you can select via the region parameter.

Quarterly map releases are named using the YYQJN format. For example, in 161J0 – the 161 indicates that the underlying base release is 2016Q1 and the letter J increments with the quarterly releases since then. The last digit N increments if there is a repair reshipment.

Weekly releases are named according to the YYQXX format. For example, in 16133 – the 161 indicates the underlying base release and the number 33 increments with the weekly releases since then. For availability of certain older map releases, contact your HERE Representative or Technical Customer Support.

Typically, HERE APIs use the latest available release of HERE core map. However, the underlying core map release can slightly differ between the different APIs. Hence, Fleet Telematics API offers all recent map releases. This way, you can retrieve additional map data from the map release that corresponds to other HERE APIs.

Customer's Maps - Bring Your Own Data

Customers can create their own private maps, with their own layers, containing points, polylines and polygons with attribution. Customer maps can be searched, retrieved and used in the same way as the HERE maps. Customers use private maps for their store locations, additional map display content and for search like a store locator.

Customer maps can also contain changes to the road network. These maps are "overlays" to the HERE map network and change Fleet Telematics API's routing 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 into and within their private facility roads, up to the individual loading docks, or to block / allow / prefer certain roads for their fleets.

A customer map can have multiple layers. As a rule of thumb, the objects that are being searched/displayed/updated together should go together into one layer. Within one layer, the map objects must be of the same type: A layer contains either points or lines or polygons. One layer might contain store locations for map display and store locator applications, another layer the arrival isoline polygons around the stores and warehouses and yet another layer the five-minute-accurate positions of the delivery trucks.

Create, visualize and manage your own data on the dashboard PRD or CIT.

Uploading Custom Maps

Customers can upload and update their private maps via Fleet Telematics API REST calls. Map layers can be uploaded in CSV plain text or in Shapefile format. Road overlay maps can be uploaded in "overlay.json" format.

Geometry rows in CSV and Shapefile format can have arbitrary attribute columns. each row in a CSV file contains the map object attributes and a WKT geometry (point, line, polygon, ...). Column names have to conform to [A-Za-z][A-Za-z0-9_]*. Column names must not contain whitespaces other than blanks (no tabs, CR, LF, backspace, unicode FFFE, or similar breaks).

Column values are plain text strings not exceeding 4000 characters in UTF-8 encoding. To create numeric columns in CSV format, add " number" behind the column name. Then numeric expressions can be applied in the search filters on those columns.

Escape characters like quotes of backslashes are not recognized (interpreted as plain characters without special semantics). The geometry column WKT in CSV files must be the last column. Otherwise, it is moved behind the last column.

If the layer contains a GEOMETRY_ID column, then it must be numeric and unique within the layer. If the layer doesn't contain a GEOMETRY_ID column, then it gets added, to uniquely identify each geometry record for actions such as modify and delete calls.

Resource https://fleet.ls.hereapi.com/2/layers/upload.json?map_name=MY_STORES&layer_id=GROCERIES&file=POI_ID%09NAME%09SIZE_SQM%09WKT%0d%0a12345%09Walmart_Munich%09650%09POLYGON((12.43236%2041.93602,12.40524%2041.86165,12.70084%2041.89233,12.70084%2041.89233,12.43236%2041.93602))&apikey=YOUR_API_KEY uploads a layer with one store. Please note that uploads should use POST requests.

Resource https://fleet.ls.hereapi.com/2/overlays/upload.json?map_name=OVERLAYTEST12345&overlay_spec=%5B%7B%22op%22%3A%22override%22%2C%22shape%22%3A%5B%5B50.10765%2C8.68774%5D%2C%5B50.10914%2C8.68771%5D%5D%2C%22layer%22%3A%22LINK_ATTRIBUTE_FCn%22%2C%22data%22%3A%7B%22VEHICLE_TYPES%22%3A%220%22%7D%7D%2C%7B%22op%22%3A%22create%22%2C%22shape%22%3A%5B%5B50.10937%2C8.68422%5D%2C%5B50.10807%2C8.68525%5D%2C%5B50.10737%2C8.68387%5D%5D%2C%22data%22%3A%7B%22NAMES%22%3A%22ENGBNDemoRoad%22%7D%7D%5D&apikey=YOUR_API_KEY uploads an overlay that changes a road access permission and adds a road. Please note that uploads should use POST requests.

Resource https://fleet.ls.hereapi.com/2/doc/maps.html?apikey=YOUR_API_KEY lists customer's private maps, https://fleet.ls.hereapi.com/2/layers/list.json?map_name=MY_STORES?apikey=YOUR_API_KEY lists the layers of a map.

Create, visualize and manage your own data on the dashboard PRD or CIT.

Custom Map Tile Size

For best search/display performance, customers can choose the tile sizes of their layers. The default is level 12 with 3 km by 3 km tiles.

If a layer contains large amounts of locally high-density geometries, such as 10,000 points within a city center of 2km x 2km, then you should choose a smaller grid size. Otherwise, each search operation in this city involves all 10,000 points. For reference, level 13 is a 1.5km x 1.5km grid and level 14 is a 750m x 750m grid.

If geometries in a layer are sparsely distributed over a big region, say 100 points around the globe, then you should choose a bigger grid size. Otherwise, each search operation operates on 10,000s of empty tiles. For reference, level 11 is a 6km x 6km grid, level 12 a 12km x 12km grid, level 13 is a 24km x 24km grid, and level 14 is a 48km x 48km grid.

Searches are limited to operate on up to 150 tiles. If this is critical then it should be considered while choosing the tile size.

Map Storage

There are two storage types available for maps: "updatable" and "readonly". You can insert/update/delete individual records and append records in "updatable" map storage. Maps in "readonly" storage cannot be modified. Instead, the full map must be uploaded again.

Updatable is the default storage for custom maps, while road overlay maps are always stored in "readonly" storage. Choose "readonly" for large maps that rarely change, because it offers higher search and retrieval performance.