Hands On

Advanced Map Data Sets - What? Why? Where?

By Shruti Kuber | 12 March 2020

When you use a mobility app like HERE WeGo for your daily commute, you can see that everyday points-of-interest like public transport stations, hospitals, schools, parks, etc. are highlighted on the map. This makes the map convenient for everyday use. But when you use maps for specific use cases like logistics, you want to see more relevant information on the map. This is one of the many use-cases where Advanced Map Layers and Data Sets can add value to your application.

The Advanced Data Sets API gives you access to a hidden chest of map layers and data sets which are a part of the rich HERE map data. This data is available in the form of attributes. These attributes can be names of EV charging stations, the text displayed on road signs, the curvature of the road, and much more. The way this data is arranged is as follows:

  • There are attributes in the form of key: value pairs
  • These attributes are grouped in the form of Layers

A call to the fleet telematics layer end point will list all layers currently available under the advanced data set.

Note: This list can change often. Make this call to get the updated list every once in a while.

https://s.fleet.ls.hereapi.com/1/doc/layers.json?apiKey={{YOUR_REST_API_KEY}} 

This call will give you a LONG list of layers and their attributes. And by LONG, I mean really LOOONG. Lets discuss a part of this response. The above call will give you something like this:


    ...
    {
        "name": "PUBLIC_TRANSPORT_POI",
        "type": "geom",
        "tileLevel": 13,
        "attributes": [
            "PLACE_ID",
            "NAMES",
            "LINK_ID",
            "CAT_ID",
            "CAT_NAME",
            "DISPLAY_LAT",
            "DISPLAY_LON",
            "SIDE_OF_STREET",
            "PERCENT_FROM_REFNODE",
            "POI_ID",
            "LAT",
            "LON"
        ],
        "featureMapping": "PDE-Base"
    },
    {
        "name": "ROAD_ROUGHNESS_FC4",
        "type": "attr",
        "tileLevel": 12,
        "attributes": [
            "LINK_ID",
            "FROM_AVG_ROUGHN_CAT",
            "TO_AVG_ROUGHN_CAT",
            "FROM_AVAILABLE_ROUGHN_TYP",
            "TO_AVAILABLE_ROUGHN_TYP",
            "FROM_AVG_IRI",
            "TO_AVG_IRI"
        ],
        "featureMapping": "PDE-Premium-Road-Info"
    },
    ...
    

So, the response gives you the name of the layer, which is essential in calling the layer when you need to use it.

The response describes the type of the layer. The type of layers can be "attr" which is attributes or "geom" which is geometry. Layers with the type geometry contain points or other map geometry objects which can be displayed as a layer over the default map. Layers with the type attributes contain attributes in the form of key:value pairs.

The response also contains the tileLevel. The tile level describes the scope of this data. This value is nothing but the zoom level of the tile. The lower the tile level, the more area the tile covers. To know more about how tiles are described, read about the system of map tiles.

The response then lists all the attribute names associated with the layer.

The value in featureMapping tells you if you need a premium account to access this layer or you can use it with a Freemium account. In the above response, the featureMapping for the layer PUBLIC_TRANSPORT_POI is PDE-Base. Thus it is available under freemium. While that for the layer ROAD_ROUGHNESS_FC4 is PDE-Premium-Road-Info, which, as the name mentions, is a premium feature. If you don't have a freemium account yet, get one at developer.here.com.

The call to the layers end point simply lists the layer names and attribute names. To get more detail about what these attributes are and what they mean, you will need to make another call to the layer end point, this time specifying the layer name. Let's see an example.


https://s.fleet.ls.hereapi.com/1/doc/layer.json?layer=ROAD_ROUGHNESS_FC2&apiKey={{YOUR_REST_API_KEY}}   

RESPONSE


    {
        "description": "The Road Roughness layers provide multiple representations of the measured roughness of a link.",
        "attributes": {
            "LINK_ID": "Permanent link ID. Positive 64 bit Integer that globally identifies the road, carto or building footprint link, also across map releases. Link IDs are never reused.",
            "FROM_AVG_ROUGHN_CAT": "Indicates the average Roughness Category applied to the link driving from reference node
. Possible values:
1 – Good
2 – Fair
3 – Poor
", "TO_AVG_ROUGHN_CAT": "Indicates the average Roughness Category applied to the link driving towards reference node
. Possible values:
1 – Good
2 – Fair
3 – Poor
", "FROM_AVAILABLE_ROUGHN_TYP": "Indicates the type of incident encountered along the link driving from reference node. Comma separated, possible values:
1 – Bump
2 – Dip", "TO_AVAILABLE_ROUGHN_TYP": "Indicates the type of incident encountered along the link driving towards reference node. Comma separated, possible values:
1 – Bump
2 – Dip", "FROM_AVG_IRI": "The average of the IRI values along driving from reference node, use to determine Roughness Category. Possible values: 0 - 99", "TO_AVG_IRI": "The average of the IRI values along driving towards reference node, use to determine Roughness Category. Possible values: 0 - 99" }, "referencedStaticContents": [], "tileRequestsLevel": 10, "tileX": 934, "tileY": 669, "isStaticContent": false }

As you can see, this call makes the picture clear with what these attributes and their values actually mean. Notice the attribute isStaticContent in the end?

While we talked about the coverage of these attributes and the type of geometry, there are certain attributes which are not tied to a specific location. Such attributes are called Static attributes. You can find a general list of available layers: Static and Non-Static here

If you already know the attribute you are looking for and need the names of the layers it is available in, you can also make a reverse call which will give you a list of attribute names and the layers which contain it.


    https://s.fleet.ls.hereapi.com/1/doc/attributes.json?apiKey={{YOUR_REST_API_KEY}}

RESPONSE


    ...
    {
        "name": "TIME_ZONE",
        "description": "Time zone defined in hours and minutes, with an offset from UTC.
As an example, EST is -060 and CET is 010.
Time Zone information is published only for the highest administrative level to which the time zone applies (e.g. Administrative Level 1 in Europe, Administrative Level 2 in the U.S.).", "layers": [ "ADMIN_PLACE_0", "ADMIN_PLACE_1", "ADMIN_PLACE_2", "ADMIN_PLACE_8", "ADMIN_PLACE_9", "ADMIN_REGULATIONS" ] }, ...

There are several ways in which these attributes and their values can be utilized in your application. Stay tuned to this series where we will take a look at these methods with examples!