Improve street match by considering drive direction

Many use cases require high precision matching GPS sensor position coordinates to roads. In applications such as connected driving, and insurance telematics, for example, it is important to match a moving position to the best possible road segment. High precision road matching can be challenging especially where roads cross or overlap each other. Where is the car traveling? On the highway, above or on the road, below? Reverse Geocoder can use a vehicle’s heading information to find the best road match in the /revgeocode endpoint. For example, information about a vehicle traveling south (not west) at the position point helps Geocoder match the position to the nearby north-south going highway, not the east-west city road.

This tutorial demonstrates how to use the feature on /revgeocode endpoint and /multi-revgeocode endpoint.

Procedure

Let's take the query as an example:

GET https://revgeocode.search.hereapi.com/v1/
    revgeocode
    ?at=51.251772,-1.078596
    &bearing=180
    &lang=en-US
    &apiKey={YOUR_API_KEY}

The following parameters are used:

at - Specify the center of the search context expressed as coordinates.
bearing - The 'bearing' parameter expresses the direction of an asset's heading in degrees, starting from true North and continuing clockwise around the compass. The values range from 0 degrees (North) to 359 degrees (just before North again). For reference, East corresponds to 90 degrees, South to 180 degrees, and West to 270 degrees. Only integer values within the range of [0;359] are allowed for the 'bearing' parameter. Other values result in a 400 error response.
lang - Select the language to be used for result rendering from a list of BCP 47 compliant language codes.
apiKey - Your API key.

📘
Note
This request uses API key authentication. For more information about authentication options on the HERE platform, see the Identity & Access Management Guide.

Input location is closer to "M3" street (marked in pink), but bearing is more relevant to "Hackwood Road" (marked in yellow).

In the response, the street result "Hackwood Road" is returned with better "bearing" match, rather than a closer street "M3" with worse "bearing" match: track position

{
    "items": [
        {
            "title": "Hackwood Road, Basingstoke, RG21 3, United Kingdom",
            "id": "here:af:streetsection:d0xsM9w-SB2XNKwpw9qjTC",
            "resultType": "street",
            "address": {
                "label": "Hackwood Road, Basingstoke, RG21 3, United Kingdom",
                "countryCode": "GBR",
                "countryName": "United Kingdom",
                "state": "England",
                "countyCode": "HAM",
                "county": "Hampshire",
                "city": "Basingstoke",
                "district": "Basingstoke",
                "street": "Hackwood Road",
                "postalCode": "RG21 3"
            },
            "position": {
                "lat": 51.25177,
                "lng": -1.07867
            },
            "distance": 5,
            "mapView": {
                "west": -1.08421,
                "south": 51.2516,
                "east": -1.07852,
                "north": 51.26198
            }
        }
    ]
}

For client applications using the feature with the /multi-revgeocode endpoint:

POST https://multi-revgeocode.search.hereapi.com/v1/
    multi-revgeocode
    ?lang=en-US
    &apiKey={YOUR_API_KEY}

HTTP Body:

id=1&at=51.251772,-1.078596&bearing=180
id=2&at=40.7305599,-73.995785&bearing=40
id=3&in=circle:51.5059910,-0.1269900;r=102&bearing=60

The streets with better "bearing" match are preferred:

{
    "results": [
        {
            "id": "1",
            "items": [
                {
                    "title": "Hackwood Road, Basingstoke, RG21 3, United Kingdom",
                    "id": "here:af:streetsection:d0xsM9w-SB2XNKwpw9qjTC",
                    "resultType": "street",
                    "address": {
                        "label": "Hackwood Road, Basingstoke, RG21 3, United Kingdom",
                        "countryCode": "GBR",
                        "countryName": "United Kingdom",
                        "state": "England",
                        "countyCode": "HAM",
                        "county": "Hampshire",
                        "city": "Basingstoke",
                        "district": "Basingstoke",
                        "street": "Hackwood Road",
                        "postalCode": "RG21 3"
                    },
                    "position": {
                        "lat": 51.25177,
                        "lng": -1.07867
                    },
                    "distance": 5,
                    "mapView": {
                        "west": -1.08421,
                        "south": 51.2516,
                        "east": -1.07852,
                        "north": 51.26198
                    }
                }
            ]
        },
        {
            "id": "2",
            "items": [
                {
                    "title": "Washington Sq E, New York, NY 10003, United States",
                    "id": "here:af:streetsection:POIumdt4bXHk.fFye7SGBA",
                    "resultType": "street",
                    "address": {
                        "label": "Washington Sq E, New York, NY 10003, United States",
                        "countryCode": "USA",
                        "countryName": "United States",
                        "stateCode": "NY",
                        "state": "New York",
                        "county": "New York",
                        "city": "New York",
                        "district": "Greenwich Village",
                        "street": "Washington Sq E",
                        "postalCode": "10003"
                    },
                    "position": {
                        "lat": 40.73052,
                        "lng": -73.99571
                    },
                    "distance": 7,
                    "mapView": {
                        "west": -73.99657,
                        "south": 40.72955,
                        "east": -73.99554,
                        "north": 40.7307
                    }
                }
            ]
        },
        {
            "id": "3",
            "items": [
                {
                    "title": "Great Scotland Yard, London, SW1A 2, United Kingdom",
                    "id": "here:af:streetsection:ExYuvQUUcHPED-uSOVKZLB",
                    "resultType": "street",
                    "address": {
                        "label": "Great Scotland Yard, London, SW1A 2, United Kingdom",
                        "countryCode": "GBR",
                        "countryName": "United Kingdom",
                        "state": "England",
                        "countyCode": "LDN",
                        "county": "London",
                        "city": "London",
                        "district": "Westminster",
                        "street": "Great Scotland Yard",
                        "postalCode": "SW1A 2"
                    },
                    "position": {
                        "lat": 51.50599,
                        "lng": -0.12698
                    },
                    "distance": 1,
                    "mapView": {
                        "west": -0.12698,
                        "south": 51.50599,
                        "east": -0.12497,
                        "north": 51.50697
                    }
                }
            ]
        }
    ]
}

types parameter: Only types=street is allowed and is used by default. The parameter is therefore optional. types values other than street result in a 400 error response.
The street with better "bearing" match is preferred if distance are similar among the streets.
If no street result matches to the bearing value, the result is a fallback to a nearby street.

Additional information

For more information about the /revgeocode and /multi-revgeocode endpoints parameters, see the API Reference.