HERE Map Attributes API is based on and offers simple access to all HERE map data and customers' private map data. Therefore the HERE Map Attributes API works with multiple maps, e.g.:
HERE Map Attributes 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 /1/doc/maps.html 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.
HERE Map Attributes 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:
Use the appropriate layer to request only the relevant data to minimize data transfer. Since the layers offered by the HERE Map Attributes API change often, check the currently supported layers with the resource Layers.
Resource /1/doc/layer.html shows the attributes (columns) of a speed limit layer.
Example speed limit layer tile content:
Sometimes, the order of the columns in the layers may change and new columns may be introduced. Make sure that your applications take this into account.
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...5Curvature, height, slope, inside-builtup
ADMIN_PLACE_0/1/2/8/9Administrative area info
ADMIN_POLY_0/1/2/8/9Administrative area geometry
BUILDINGBuilding type, height, footprint geometry
CARTO_LINE_DO0/1/2/8/9Cartographic line type, name, geometry
CARTO_POLY_DO0/1/2/8/9Cartographic polygon type, name, geometry
CARTO_POLY_OCEANCartographic ocean polygon name, geometry
CARTO_POLY_RIVER_DO0/1/2/8/9Cartographic river polygon type, name, geometry
CARTO_POLY_TOLL_HAZCartographic toll zone and hazardous area polygon name, geometry
CENSUS_0/1/2/8/9Basic census area info
CEN_*Country-specific census info
CITY_POI_0/1/2/8/9City center POI info, location
DISTANCE_MARKERS_FC1...5Distance marker info, location
DTM_HEIGHTDigital terrain model grid height
EVCHARGING_POIElectric vehicle charging station info, location
FUELSTATION_POIgasoline, diesel, and EV charging offerings
JUNCTION_VIEW 2Djunction info, location, reference to image
LANE_CONN_FC1...5Lane level guidance link connectivity info
LINK_ATTRIBUTE2_FC1...5Advanced link info for routing, map display
LINK_ATTRIBUTE_FC1...5Basic link info for routing, map display
LINK_FC1...5Link connectivity info for routing, guidance
LINK_TMC_FC1...5LINK TMC for live traffic processing
MICROPOINT_ADDRESSAddress location, info with house number building unit and level for map display
NATURAL_GUIDANCENatural guidance info
POINT_ADDRESSAddress location, info with house number for map display
POI_BIGPoint of interest info, location for map display
POI_BIGGERPoint of interest type, info, location for map display
POI_SMALLPoint of interest type, info, location for map display
POI_SMALLERPoint of interest type, info, location for map display
PSTLCB_GENPostal code boundary generalized geometry
PSTLCB_MPPostal code boundary mid point location
PSTLCB_UNGENPostal code boundary geometry
PSTLCMIDPPostal code area mid point location for map display
PUBLIC_TRANSPORT_POIPublic transport stop locations, like bus stops and subway stations for map display
ROAD_ADMIN_FC1...5Road link's administrative hierarchy, postal code
ROAD_ADMIN_NAMES_FC1...5Road link's official names of the admin hierarchy (builtup, city, district, state, country).
ROAD_GEOM_FC1...5Road link info, geometry for map display
ROAD_NAME_FC1...5Road link name
ROAD_OVERVIEWGeneralized rad geometry for map display
ROAD_ROUGHNESS_FC1...5Classification of the road surface roughness for driver warning
ROUTING_FC1...5Compact representation of link info, connectivity, conditions for routing
SAFETY_ALERTSLocations of accident spots and speed cameras, for driver warning
SIGNPOSTDirection sign info
SPEED_LIMITS_COND_FC1...5Conditional speed limit info
SPEED_LIMITS_FC1...5Car speed limit info
SPEED_LIMITS_VAR_FC1...5Variable speed sign info
STAB_TOPO_ID_FC1...5maps between Link IDs and their corresponding Stable Topology IDs with offset.
TOLLCOST_FC1...5Road toll cost info for toll calculation/optimization
TOLL_BOOTH_FC1...5Toll booth info for toll calculation/optimization
TOLL_LINK_FC1...5Road link toll info for toll calculation/optimization
TRAFFIC_PATTERN_FC1...5Typical link speed per time of day and weekday
TRAFFIC_SIGN_FC1...5Traffic sign info for driver alerts
TRAFFIC_SPEED_RECORD_FC1...5Live traffic info recorded from the last days, at a 15 minute resolution
TRUCK POITruck-specific rest area and restaurant info
TRUCK_RESTR_FC1...5Truck restriction info for routing
TRUCK_SPEED_LIMITS_FC1...5Truck speed limit info
TURN_RESTR_FC1...5Turn restriction info
VIRT_CONNVirtual connection link info, geometry for routing, map display
The following non-tiled (static) layers are available:
ADMIN_REGULATIONSAdministrative level regulations, time zones
ADMIN_TRUCK_RESTRAdministrative level truck restrictions
TC_ADMINAdministrative level road toll info
TC_SYSTEMToll operator info
TC_TOLLSYS_NAMESToll operator names
TC_VEH_TYPESToll vehicle type info
TRAFFIC_PATTERNTraffic speed curves
For more details and licensing info, see the /doc/layers.html service documentation.
Resource /1/docs/maps.html shows the available core map layers.
Some layers contain non-spatial data (independent of locations), e.g. toll vehicle type definitions. HERE Map Attributes 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
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 HERE Map Attributes 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 /1/file.bin retrieves a junction view image.
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 /1/doc/indexes.html 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 /1/index.json finds in which road geometry layer's tiles the link IDs 17339738 and 17339811 reside.
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.
The world map in above figure is flattened via Mercator projection.
However, layer tiling is based on unprojected WGS 84 degrees; not Mercator.
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:
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:
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) tileID = tileY * 2 * (2^level) + tileX
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:
The HERE map is divided into the following regions:
Requests to the HERE Map Attributes 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.
HERE updates map content weekly. By default, HERE Map Attributes 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 release parameter. Please contact Technical Customer Support for availability and pricing of older map content.
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 Routing service's 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.
Customers can upload and update their private maps via HERE Map Attributes 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 /2/layers/upload.json)&apikey=YOUR_API_KEY ) uploads a layer with one store. Please note that uploads should use POST requests.
Resource /2/overlays/upload.json uploads an overlay that changes a road access permission and adds a road. Please note that uploads should use POST requests.
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.
There are two storage types available for custom 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.