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 Traffic API v7, 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

Length

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

"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.

HERE's Location Library can decode TMC location references. For more information, see the Location Library documentation Working with TMC References.

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
}

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.

HERE's Location Library can decode OLR location references. For more information, see the Location Library documentation Working with 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.

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
        },
        {
            "points": [
                {
                    "lat": 52.501959996297956,
                    "lng": 13.703020038083196
                },
                {
                    "lat": 52.502879993990064,
                    "lng": 13.703829981386662
                }
            ],
            "length": 116.0
        },
        {
            "points": [
                {
                    "lat": 52.502879993990064,
                    "lng": 13.703829981386662
                },
                {
                    "lat": 52.50310001894832,
                    "lng": 13.704029973596334
                },
                {
                    "lat": 52.504169968888164,
                    "lng": 13.704979978501797
                }
            ],
            "length": 163.0
        },
        {
            "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
        }
    ]
}