Using house number fallback

This tutorial demonstrates how the API manages house number fallback.

Procedure

It may happen, that the house number, which one is looking for, is not yet in the map data. For example, the house is still being built. For such cases, the HERE Geocoding and Search /geocode returns the nearest known house number on the same street.

For example, address Ringelsteinweg 11, 14165 Berlin is not available in the map data (and does not exist in reality). The nearest known house number on this street is 7.

GET https://geocode.search.hereapi.com/v1/
    geocode
    ?q=Ringelsteinweg+11%2C+14165+Berlin
    &apiKey={YOUR_API_KEY}

The /geocode cannot find house number 11 and instead returns house number 7:

{
  "items": [
    {
      "title": "Ringelsteinweg 7, 14165 Berlin, Deutschland",
      "id": "here:af:streetsection:qI3rHJl.RsGumDzYSgMCkB:CgcIBCCBnaRQEAEaATcoZA",
      "resultType": "houseNumber",
      "houseNumberType": "PA",
      "address": {
        "label": "Ringelsteinweg 7, 14165 Berlin, Deutschland",
        "countryCode": "DEU",
        "countryName": "Deutschland",
        "stateCode": "BE",
        "state": "Berlin",
        "countyCode": "B",
        "county": "Berlin",
        "city": "Berlin",
        "district": "Zehlendorf",
        "street": "Ringelsteinweg",
        "postalCode": "14165",
        "houseNumber": "7"
      },
      "position": {
        "lat": 52.41003,
        "lng": 13.26192
      },
      "access": [
        {
          "lat": 52.41007,
          "lng": 13.26191
        }
      ],
      "mapView": {
        "west": 13.26045,
        "south": 52.40913,
        "east": 13.26339,
        "north": 52.41093
      },
      "houseNumberFallback": true,
      "scoring": {
        "queryScore": 0.99,
        "fieldScore": {
          "city": 1,
          "streets": [
            1
          ],
          "houseNumber": 0.96,
          "postalCode": 1
        }
      }
    }
  ]
}

The response includes an additional high-level element - flag "houseNumberFallback": true- indicating that the requested house number was corrected to match the nearest known house number. The score of house number field is not anymore equal to 1, but 0.96 - reduced by 4 points, which represent numeric distance between requested and returned house numbers The total query score is also reduced.

Additional information

For more information about/geocode parameters, see: API Reference.