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 following parameters are used:
- q - Enter a free-text query.
- 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.
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.