Multi-Reverse geocode

The /multi-revgeocode endpoint is designed to increase the throughput performance of Reverse Geocoding requests.

The endpoint allows the retrieval of up to one hundred address locations with one multi-reverse geocoding request.

For example, a user tries to retrieve multiple addresses/places in Frankfurt, and submits the multiple geo-coordinates in a request to the /multi-revgeocode endpoint.

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

POST Request Body:

Contains the location context as well as a string identifier in the id parameter as plain text

Identifier

id: An identifier for each item in the POST request body is required. Values must be unique per request, with a size limit of 64 characters and can only contain alphanumeric characters or an underscore or dash.

Location context provided through any of the following:

a single geo-position: at - Specify the center of the search context expressed as coordinates
a circle: in - Search within a geographic area

Both location contexts are mutually exclusive.

Location context is only allowed in the POST request body

Except above supported parameters, other parameters are not allowed in the POST request body

The maximum number of locations to be reverse geocoded per multi-reverse geocode request is 100

Example of POST request body:

id=1&at=50.11059,8.68407
id=2&at=50.11091,8.68328
id=3&in=circle:50.0911262,8.700627;r=2000

For this example, the API returns the nearest address/place to each input coordinates:

{
    "results": [
        {
            "id": "1",
            "items": [
                {
                    "title": "Bendergasse 6, 60311 Frankfurt, Germany",
                    "id": "here:af:streetsection:a-a.uU.9-.CFWcuyP5IA6A:CggIBCCqt4nnAhABGgE2",
                    "resultType": "houseNumber",
                    "houseNumberType": "PA",
                    "address": {
                        "label": "Bendergasse 6, 60311 Frankfurt, Germany",
                        "countryCode": "DEU",
                        "countryName": "Germany",
                        "stateCode": "HE",
                        "state": "Hesse",
                        "countyCode": "F",
                        "county": "Frankfurt",
                        "city": "Frankfurt",
                        "district": "Altstadt",
                        "street": "Bendergasse",
                        "postalCode": "60311",
                        "houseNumber": "6"
                    },
                    "position": {
                        "lat": 50.11052,
                        "lng": 8.68398
                    },
                    "access": [
                        {
                            "lat": 50.11042,
                            "lng": 8.68402
                        }
                    ],
                    "distance": 10,
                    "mapView": {
                        "west": 8.68278,
                        "south": 50.1102,
                        "east": 8.68483,
                        "north": 50.11054
                    }
                }
            ]
        },
        {
            "id": "2",
            "items": [
                {
                    "title": "Hinter dem Lämmchen 6, 60311 Frankfurt, Germany",
                    "id": "here:af:streetsection:zYplws4aR53N0u05iAHEtD:CggIBCDPxInnAhABGgE2",
                    "resultType": "houseNumber",
                    "houseNumberType": "PA",
                    "address": {
                        "label": "Hinter dem Lämmchen 6, 60311 Frankfurt, Germany",
                        "countryCode": "DEU",
                        "countryName": "Germany",
                        "stateCode": "HE",
                        "state": "Hesse",
                        "countyCode": "F",
                        "county": "Frankfurt",
                        "city": "Frankfurt",
                        "district": "Altstadt",
                        "street": "Hinter dem Lämmchen",
                        "postalCode": "60311",
                        "houseNumber": "6"
                    },
                    "position": {
                        "lat": 50.11096,
                        "lng": 8.68333
                    },
                    "access": [
                        {
                            "lat": 50.11092,
                            "lng": 8.68335
                        }
                    ],
                    "distance": 5,
                    "mapView": {
                        "west": 8.68311,
                        "south": 50.11087,
                        "east": 8.68377,
                        "north": 50.111
                    }
                }
            ]
        },
        {
            "id": "3",
            "items": [
                {
                    "title": "Schnappbornweg 85, 60599 Frankfurt, Germany",
                    "id": "here:af:streetsection:hMoVrRaebf3FidQKfKyL4A:EAIaAjg1",
                    "resultType": "houseNumber",
                    "houseNumberType": "interpolated",
                    "address": {
                        "label": "Schnappbornweg 85, 60599 Frankfurt, Germany",
                        "countryCode": "DEU",
                        "countryName": "Germany",
                        "stateCode": "HE",
                        "state": "Hesse",
                        "countyCode": "F",
                        "county": "Frankfurt",
                        "city": "Frankfurt",
                        "district": "Sachsenhausen",
                        "street": "Schnappbornweg",
                        "postalCode": "60599",
                        "houseNumber": "85"
                    },
                    "position": {
                        "lat": 50.0909,
                        "lng": 8.70081
                    },
                    "access": [
                        {
                            "lat": 50.09078,
                            "lng": 8.7009
                        }
                    ],
                    "distance": 29,
                    "mapView": {
                        "west": 8.69652,
                        "south": 50.08983,
                        "east": 8.70564,
                        "north": 50.09366
                    }
                }
            ]
        }
    ]
}

The response includes:

The identifier which is specified in the corresponding request item
Complete address description and its location

It delivers the following high-level elements for each result:

id- The identifier associates each result with the corresponding input.
resultType - HERE Geocoding and Search /multi-revgeocode endpoint is able to return items of several types: houseNumber, place, locality, street, etc.
houseNumberType - type of address data (returned only for address results):
- PA - Point Address, location matches as individual point object
- interpolated - location is the interpolated point on an address range line object
title – a representative string for the result. In case of address it is the complete postal address string
address - the detailed address of the result
position - a representative geo-position (WGS 84) of the result. This is used to display the result on a map
access - the geo-position of the access to the result (for instance the entrance)
mapView - bounding box of the location optimized for display
distance - the /multi-revgeocode endpoint returns the distance in meters to the given spatial context ('at=lat,lon')
id - the identifier of the result object. Its value can be used to retrieve the same object through the /lookup endpoint.

In case of an error, HTTP response code and error message are returned, "id" is also returned for the error from the sub-request.

More details about the /multi-revgeocode endpoint parameters can be found in the API Reference.

📘
Note:

The /multi-revgeocode endpoint is not available for self-serve customers. For more information, contact your HERE representative.