Referencing HERE Map Content entities

Introduction

Location services often return references to map entities. In general the following information needs to be provided:

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 (example BYOD).
map version: from which map version the entity has been extracted.
metadata: entity specific extra metadata. For example, we can reference only a part of a topologySegment or a specific direction.

Design considerations

Topology segments
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 can be used across libraries and services to exchange references to map entities.

We provide a generic EntityReference that should work for most of the cases and a special SegmentReference that is specific for referencing topology segments.

Entity references

A reference to a map entity has the form of an HRN with 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 can be found. The layer is not provided if the referenced data is scattered on multiple layers
partitionId/tileId:
- HERETile partitioning: This is a TileId where this identifier is located in the given version of the map (level 12-15).
- Generic partitioning: This is the partition as defined in the corresponding layer.
entityIdentifier: full identifier of the entity inside the catalog.

entityMetadata: entity specific extra metadata.

Control characters like "$", "#" or ":" are not allowed.

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, it can only be interpreted in combination with the corresponding refReplacements. Replacing all placeholders should yield an EntityReference. example: "$0:23618402:$1:5262h5rn-8835451b09847bab46cd822794f35697" pattern: '(^|:)$\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 HRN one has to replace all placeholders with the replacement strings from the refReplacement response parameter.

The above representation can be used when exchanging few referenced, for example as query parameters (method GET). An alternative compact representation is defined for structured requests/responses (normally in JSON).

The representation is composed by an object containing replacement strings and compact references which will include placeholders for the replacements:

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.

Referencing entities