GuidesAPI Reference
Guides
  1. HERE Traffic API v7 Developer Guide
  2. HERE Traffic API v7 concepts

Location referencing

A location reference describes a location. A location can be a particular point, curve, or two-dimensional shape on the surface of the earth. Quite often, when a location is used in an application, it refers to a particular anthropogenic or geographic feature, such as a road, building, mountain, or body of water.

Within the HERE Traffic API, location referencing focuses on locations that describe roadways.

The three supported location referencing types are:

  • TMC (Traffic Message Channel)
  • OLR (OpenLR Location Referencing)
  • Shape Points
  • Topology Segments

Length

For all location referencing types, the total length of the location reference is provided on the Location object in the length field, which is reported in meters.

"length": 659.0

TMC

Traffic Message Channel (TMC) location referencing method uses tables of pre-coded locations. For details refer the specifications ISO 14819-2:2013 and ISO 14819-3:2013.

The HERE Location Library can decode TMC location references. For more information, see the Location Library documentation TMC.

The TMC information is provided in the tmc field:

"tmc": {
    "extendedCountryCode": "E0",
    "ebuCountryCode": "D",
    "tableId": "1",
    "locationId": "10429",
    "queuingDirection": "-",
    "extent": 1,
    "primaryOffset": 0.0,
    "affectedLength": 634.0
}
📘

Note

Among the tmc field, queuingDirection represents the TMC queuing direction of traffic. When traffic becomes congested, a queue of vehicles begins to build up in the opposite direction to the driving direction, as such the queuing direction and the travel direction of a TMC are opposite. The value can be "+" or "-". The value "+" indicates that the queuing-direction is same as the link-direction while the value "-" indicates that the queuing-direction is opposite to the link-direction.

The TMC network does not cover all roads. When only TMC location referencing is requested, then some results may be filtered out as there is no way to represent that location with a TMC.

OLR

The OpenLR Location Referencing (OLR) method defines rules for generating map-independent location references, that is, the actual location references are generated dynamically and do not require the use of pre-defined location references.

An OLR can reference any roadway, not only a restricted set as is the case for TMC referencing. For more information, see the specification ISO/TS 21219-22:2017.

OLR is a binary format as described in the specification above. The OLR data is encoded in a Base64 string within the response. For more information on Base64 encoding, see RFC 4648.

The HERE Location Library can decode OLR location references. For more information, see the Location Library documentation OLR for details.

The OLR string is provided in the olr field:

"olr": "CCoBEAAmJQm+WSVVfAAJBQQCAxoACgUEAogZAAHtA2UACQUEAgOEADBigj0="

Shape points

Shape points location referencing is the simplest method. For each link in the referenced map, the shape is described by a list of WGS84 coordinates as well as the length of the link.

📘

Note

The shape points of each link are consecutive, forming the polyline for that link.

Returned links may not be consecutive, as a location may be from a split TMC (a fork) or may have non-traversable links in the middle.

The links returned for shape point location references are not guaranteed to be consecutive. You might see cases where the last shape point of a link is not identical to the first shape point of the next link.

The shape points are provided in the shape field:

"shape": {
    "links": [
        {
            "points": [
                {
                    "lat": 52.501569986343384,
                    "lng": 13.702660035341978
                },
                {
                    "lat": 52.50179001130164,
                    "lng": 13.702860027551651
                },
                {
                    "lat": 52.501959996297956,
                    "lng": 13.703020038083196
                }
            ],
            "length": 50.0,
            "functionalClass": 3
        },
        {
            "points": [
                {
                    "lat": 52.501959996297956,
                    "lng": 13.703020038083196
                },
                {
                    "lat": 52.502879993990064,
                    "lng": 13.703829981386662
                }
            ],
            "length": 116.0,
            "functionalClass": 3
        },
        {
            "points": [
                {
                    "lat": 52.502879993990064,
                    "lng": 13.703829981386662
                },
                {
                    "lat": 52.50310001894832,
                    "lng": 13.704029973596334
                },
                {
                    "lat": 52.504169968888164,
                    "lng": 13.704979978501797
                }
            ],
            "length": 163.0,
            "functionalClass": 3
        },
        {
            "points": [
                {
                    "lat": 52.504169968888164,
                    "lng": 13.704979978501797
                },
                {
                    "lat": 52.504879999905825,
                    "lng": 13.70560996234417
                },
                {
                    "lat": 52.50540001317859,
                    "lng": 13.706069961190224
                },
                {
                    "lat": 52.505700001493096,
                    "lng": 13.70631999336183
                },
                {
                    "lat": 52.50596000812948,
                    "lng": 13.706470029428601
                },
                {
                    "lat": 52.50616000033915,
                    "lng": 13.706549992784858
                },
                {
                    "lat": 52.50644003972411,
                    "lng": 13.706600032746792
                },
                {
                    "lat": 52.50668001361191,
                    "lng": 13.706589974462986
                },
                {
                    "lat": 52.50691001303494,
                    "lng": 13.706559967249632
                }
            ],
            "length": 330.0,
            "functionalClass": 3
        }
    ]
}

Topology Segments

The Topology Segment references defines a location by a series of reference to the HMC Topology Segment.

The standard representation of a segment reference has the following structure:

{catalogHrn}:{catalogVersion}:({layerId})?:{tileId}:{segmentId}(#{direction}({startOffset}..{endOffset})?)?

Response structure also contains length field that is a representation of the topology segment length from start offset to end offset.

The individual parts are:

  • catalogHrn: The HERE Resource Name that identifies the source catalog of the segment, example: hrn:here:data::olp-here:rib-2
  • catalogVersion: The catalog version
  • layerId (optional): The layer inside the catalog where the segment can be found, example: topology-geometry
  • tileId: The HERE tile key of the partition/tile where the segment is located in the given version of the catalog. This can be on a lower level than the actual segment is stored at (for example, the provided tile ID can be on level 14, despite topology-geometry partitions being tiled at level 12). The level of a HERE tile key is indicated by the position of the highest set bit in binary representation. Since the HERE tile key represents a morton code of the x and y portion of the Tile ID, the level 12 tile ID can be retrieved from the level 14 tile ID by removing the 4 least significant bits (or 2 bits per level) or 1 hexadecimal digit. For example, the level 14 tile 377894441 is included in the level 12 tile 23618402 (37789444110 = 1686362916 → 168636216 = 2361840210)
  • segmentId: The identifier of the referenced topology segment inside the catalog, example: here:cm:segment:84905195
  • direction (optional): Either '*' for undirected or bidirectional, '+' for positive direction, '-' for negative direction, or '?' for unknown direction (not used by the routing service)
  • startOffset/endOffset (optional): The start- and end offset are non-negative numbers between 0 and 1, representing the start and end of the referenced range using a proportion of the length of the segment. 0 represents the start and 1 the end of the segment, relative to the indicated direction (or positive direction in case of undirected segments). Example: 0.7..1

The segment references can also be provided in a compact representation, to reduce the response size. In the compact representation, some parts are replaced by placeholders, which can be resolved using the refReplacements dictionary in the parent section.

The placeholder format is \$\d+ and needs to be surrounded by colons or string start/end. It can be captured with the following regular expression: (^|:)\$\d+(:|$)/.

📘

Note

The format is the same as used when requesting segment refs in spans in the Routing API

Topology Segment references are provided in the segmentRef field and replacement strings are in refReplacements field (if requested, it is used for compact representation of HMC topology segment references):

Example of the segment reference in compact representation:

"segmentRef": {
    "segments": [
        {
            "ref": "$0:377894504:$1:87964630#-0.77195..0.99348",
            "length": 47
        },
        {
            "ref": "$0:377894504:$1:82804623#-0..0.08525",
            "length": 21
        }
    ]
}

refReplacements field:

"refReplacements": {
    "0": "hrn:here:data::olp-here:rib-2:5447:",
    "1": "here:cm:segment"
}

Example of a segment reference in standard representation without refReplacements:

"segmentRef": {
    "segments": [
        {
            "ref": "hrn:here:data::olp-here:rib-2:5447::377893833:here:cm:segment:661789549#-0.58984..1",
            "length": 28
        }
    ]
}

Updated last month