Guides
Guides
  1. Introduction to Mapping Concepts User Guide

References to HERE Map Content entities

Location services often return references to map entities. In general, Location services provide the following information:

  • identifier: the unique identifier of an entity
  • partition/tile: where to find this identifier in the map data
  • map hrn: which map is the source of the data. A response could include entities sourced from different maps.
  • map version: the map version containing the source entity.
  • metadata: entity specific extra metadata. For example, HERE can reference only a part of a topologySegment or a specific direction.

Design considerations

  • Topology segments
  • Places such as POIs, many of which have street addresses to facilitate navigation. See the Points-of-Interest topic for details on geocoding places
  • Administrative places
  • Fuel Station/EV charging stations
  • Toll zones/Environmental zones

Use cases

  • Service to Service
  • Service to Catalog/Data service
  • Catalog/Data service to Service
  • Catalog/Data service to Catalog/Data service

Location reference definitions

Location reference definitions are a collection of definitions that you can use across libraries and services to exchange references to map entities.

HERE provides a generic EntityReference that should work for most of the cases and a special SegmentReference that's specific for referencing topology segments.

Entity references

A reference to a map entity has the following structure. Format: {catalogHrn}:{catalogVersion}:({layerId})?:{partitionId/tileId}:{entityIdentifier}(#{entityMetadata})?

where:

  • catalogHrn: Catalog HRN
  • catalogVersion: Catalog version
  • layerId (optional): layer identifier inside the catalog where the entity lives. The identifier doesn't provide the layer for an entity when its data lives in multiple layers
  • partitionId/tileId:
    • HERETile partitioning: A TileId where this identifier is in the given version of the map at level 12-15.
    • Generic partitioning: The partition as defined in the corresponding layer.
  • entityIdentifier: full identifier of the entity inside the catalog.
  • entityMetadata: entity specific extra metadata.
    • You can't use control characters like "$", "#" or ":"

Examples:

    Place reference: 
        hrn:here:data::olp-here:rib-2:4829:electric-vehicle-charging-stations:23618403:here:pds:place:276u33de-35e6b730b28b43eeb64518ec41f5b4c3
    TopologySegment:
        hrn:here:data::olp-here:rib-2:4823::377894444:here:cm:segment:97139412
    Directed TopologySegment:
        hrn:here:data::olp-here:rib-2:4823::377894444:here:cm:segment:97139412#+
    Range Based segment:
        hrn:here:data::olp-here:rib-2:4823::377894444:here:cm:segment:97139412#+0.2..0.8

An identifier for the segment in the format of domain:system:type:id, for example, "here:cm:segment:3455277". This property is unique in a catalog.

Compact entity references

Compact entity references are EntityReference that use placeholders to shorten repeated substrings.

If the reference contains placeholders, you can interpret it only in combination with the corresponding refReplacements.

Replacing all placeholders should yield an EntityReference.

Example: $0:23618402:$1:5262h5rn-8835451b09847bab46cd822794f35697</code><br> Pattern: <code>(^|:)\$\d+(:|$)

With the corresponding refReplacements:

"refReplacements": {
  "0": "hrn:here:data::olp-here:rib-2:3217:environmental-zones",
  "1": "here:cm:envzone",
  "2": "hrn:here:data::olp-here:rib-2:3217:",
  "3": "here:cm:segment"
},

To reconstruct a complete path, you must replace all placeholders with the replacement strings from the refReplacement response parameter.

The above representation works when exchanging few references, for example as query parameters (method GET). An alternative compact representation works for structured requests/responses.

The following representation shows an object containing replacement strings and compact references:

refReplacements: object {index} → {referencePart}
    index: placeholder index. Format \d+
    referencePart: part of the reference that can be replaced at the given index.
reference: entity reference as described above but where some parts are replaced by placeholders.
    The placeholder format is \$\d+ and need to be surrounded by colons or string start/end.
        It can be captured with the following regular expression: (^|:)\$\d+(:|$)
    Examples:
        Valid placeholders: $0:23:layer1:41879514:$1:5262h5rn-8835451b09847bab46cd822794f35697
        Invalid placeholder: $0:23:layer1:41879514:$1:$2-8835451b09847bab46cd822794f35697

Examples

Places
{
    "refReplacements": {
        "0": "hrn:here:data::olp-here:rib-2:23:electric-vehicle-charging-stations",
        "1": "here:pds:place",
        "2": "customer1:data::my-realm:map:4:electric-vehicle-charging-stations",
        "3": "xxx:yyy:place"
    },
    ...
    "places": [
        { ...,
          "placeRef": "$0:41879513:$1:7762h5rn-77262d51b09847bab46cd822794f919e"
        },
        { ...,
          "placeRef": "$0:41879514:$1:5262h5rn-8835451b09847bab46cd822794f35697"  
        },
        ...      
        { ...,
          "placeRef": "$2:41879513:$3:4683213516541320"
        }
    ]
}
Topology Segments
{ 
  "refReplacements": {
    "0": "hrn:here:data::olp-here:rib-2:42:",   /* note the trailing column to denote a missing layerId */
    "1": "hrn:here:data::olp-here:here-map-content-japan-2:5:"
    "2": "here:cm:segment",
    "3": "here:xs1:segment"
  },
  ...
  "segments": [
    {"ref": "$0:23618402:$2:170299229#+0.6..1"},
    {"ref": "$0:23618402:$2:170299229#+"},
    ...
    {"ref": "$0:23618402:$2:100633204#-"},
    {"ref": "$0:23618402:$2:103074267#+0..0.4"},
    {"ref": "$1:23618402:$3:101400170#+0.27..1"}
    {"ref": "$1:23618402:$3:201933605#-"}
    {"ref": "$1:23618402:$3:201933605#+"}
    {"ref": "$1:24330788:$3:5851092#-0..0.81"}
  ]
}

Topology segments metadata

Topology segments can contain extra metadata with the following format: {direction}({range}|{point})?

    direction format: 
        * This is an undirected or bidirectional segment.
        + This is a directed segment following the pre-defined segment direction (forward direction). The pre-defined segment direction is the one going from the start node to the end node as defined in the source catalog.
        - This is a directed segment following the opposite direction (backward direction).
        ? The segment has an unknown direction.
    range format: {startOffset}..{endOffset}
        startOffset <= endOffset
    point format: offset

All offsets are non-negative float numbers between 0 and 1 with the format [01](\.\d+)? and represent positions in the segment. For directed segments, offsets are always relative to the segment direction, while for undirected segments the offsets are relative to the forward direction.

Updated last month