Address results
HERE Geocoding and Search returns highly granular address related results.
Those are of resultType
values locality
, street
, houseNumber
, administrativeArea
, addressBlock
, intersection
, postalCodePoint
.
Each of these address results can have an additional sub-type that allows a finer grained triaging. For instance a locality result, can be of locality sub-type city
, postalCode
, district
or subdistrict
.
The address subtypes can be summed up with the following table:
resultType value | sub-type field | sub-type field values |
locality | localityType | city
postalCode
district
subdistrict |
administrativeArea | administrativeAreaType | country
state
county |
houseNumber | houseNumberType | PA
interpolated |
addressBlock | addressBlockType | block
subblock |
intersection | (none) | |
street | (none) | |
postalCodePoint | (none) |
Note that the type of an address result represents the highest granularity of the address. For instance, a houseNumber
-type result will always contain a houseNumber
field in the address
response element Additional elements are street
, city
and country
fields. A street
-type result itself won't have a houseNumber
field in the address
response element.
Locality
Results of type locality
have an additional field localityType
that further defines results of types: postalCode
, city
, district
, subdistrict
WARNING
New localityType
values can get added to the list without further notice. Applications using HERE Geocoding and Search must not assume the list is fixed.
Examples of results for each localityType
value:
-
city
Paris, Ile-de-France, France:
{
"title": "Paris, Ile-de-France, France",
"id": "here:cm:namedplace:20002128",
"resultType": "locality",
"localityType": "city",
"address": {
"label": "Paris, Ile-de-France, France",
"countryCode": "FRA",
"countryName": "France",
"stateCode": "IDF",
"state": "Ile-de-France",
"county": "Paris",
"city": "Paris",
"postalCode": "75001"
},
"position": { "lat": 48.85717, "lng": 2.3414 },
"mapView": { "west": 2.22383, "south": 48.81571, "east": 2.4698, "north": 48.90248 }
}
-
postalCode
10965, Berlin, Germany:
{
"title": "10965, Berlin, Germany",
"id": "here:cm:namedplace:22067656",
"resultType": "locality",
"localityType": "postalCode",
"address": {
"label": "10965, Berlin, Germany",
"countryCode": "DEU",
"countryName": "Germany",
"stateCode": "BE",
"state": "Berlin",
"countyCode": "B",
"county": "Berlin",
"city": "Berlin",
"postalCode": "10965"
},
"position": { "lat": 52.48663, "lng": 13.38445 },
"mapView": { "west": 13.42115, "south": 52.47668, "east": 13.36716, "north": 52.49658 }
}
-
district
Back Bay, Boston, MA, United States:
{
"title": "Back Bay, Boston, MA, United States",
"id": "here:cm:namedplace:23026323",
"resultType": "locality",
"localityType": "district",
"address": {
"label": "Back Bay, Boston, MA, United States",
"countryCode": "USA",
"countryName": "United States",
"stateCode": "MA",
"state": "Massachusetts",
"county": "Suffolk",
"city": "Boston",
"district": "Back Bay"
},
"position": { "lat": 42.35093, "lng": -71.07606 },
"mapView": { "west": -71.09317, "south": 42.33982, "east": -71.06046, "north": 42.36159 }
}
-
subdistrict
Dig Area, Gole Market, New Delhi, Delhi, India:
{
"title": "Dig Area, Gole Market, New Delhi, Delhi, India",
"id": "here:cm:namedplace:27681054",
"resultType": "locality",
"localityType": "subdistrict",
"address": {
"label": "Dig Area, Gole Market, New Delhi, Delhi, India",
"countryCode": "IND",
"countryName": "India",
"stateCode": "DL",
"state": "Delhi",
"county": "New Delhi",
"city": "New Delhi",
"district": "Gole Market",
"subdistrict": "Dig Area",
"postalCode": "110001"
},
"position": { "lat": 28.6351, "lng": 77.2034 },
"mapView": { "west": 77.19864, "south": 28.6282, "east": 77.20862, "north": 28.64109 }
}
Endpoints returning locality
results: /discover
, /autosuggest
, /lookup
, /browse
, /geocode
, /autocomplete
, /revgeocode
Administrative area
Results of type administrativeArea
have an additional field administrativeAreaType
that further defines results of types: country
, state
, county
WARNING
New administrativeAreaType
values can get added to the list without further notice. Applications using HERE Geocoding and Search must not assume the list is fixed.
Examples of results for each administrativeAreaType
value:
-
country
Andorra:
{
"title": "Andorra",
"id": "here:cm:namedplace:20300625",
"resultType": "administrativeArea",
"administrativeAreaType": "country",
"address": {
"label": "Andorra",
"countryCode": "AND",
"countryName": "Andorra",
},
"position": { "lat": 42.50514, "lng": 1.52604 },
"mapView": { "west": 1.41382, "south": 42.42873, "east": 1.78659, "north": 42.65601 }
}
-
state
CA, United States:
{
"title": "CA, United States",
"id": "here:cm:namedplace:21009408",
"resultType": "administrativeArea",
"administrativeAreaType": "state",
"address": {
"label": "CA, United States",
"countryCode": "USA",
"countryName": "United States",
"stateCode": "CA",
"state": "California"
},
"position": { "lat": 38.57944, "lng": -121.49085 },
"mapView": { "west": -124.40962, "south": 32.53429, "east": -114.13084, "north": 42.00946 }
}
-
county
Bern-Mittelland, Berne, Switzerland:
{
"title": "Bern-Mittelland, Berne, Switzerland",
"id": "here:cm:namedplace:20138838",
"resultType": "administrativeArea",
"administrativeAreaType": "county",
"address": {
"label": "Bern-Mittelland, Berne, Switzerland",
"countryCode": "CHE",
"countryName": "Switzerland",
"stateCode": "BE",
"state": "Berne",
"county": "Bern-Mittelland"
},
"position": { "lat": 46.89559, "lng": 7.46262 },
"mapView": { "west": 7.08269, "south": 46.67091, "east": 7.73215, "north": 47.12267 }
}
Endpoints returning administrativeArea
results: /discover
, /autosuggest
, /lookup
, /browse
, /geocode
, /autocomplete
, /revgeocode
Address block
Results of type addressBlock
are part of the Japanese addressing system. The results have an additional field addressBlockType
that further defines results of types: block
, subblock
WARNING
New addressBlockType
values can get added to the list without further notice. Applications using HERE Geocoding and Search must not assume the list is fixed.
Examples of results for each addressBlockType
value:
-
block
Yo Wakuramachi, Nanao-shi, Ishikawa, 926-0175 Japan:
{
"title": "Yo Wakuramachi, Nanao-shi, Ishikawa, 926-0175 Japan",
"id": "here:xs1:namedplace-loc:45000060",
"resultType": "addressBlock",
"addressBlockType": "block",
"address": {
"label": "Yo Wakuramachi, Nanao-shi, Ishikawa, 926-0175 Japan",
"countryCode": "JPN",
"countryName": "Japan",
"state": "Ishikawa",
"city": "Nanao-shi",
"subdistrict": "Wakuramachi",
"block": "Yo",
"postalCode": "926-0175"
},
"position": { "lat": 37.08958, "lng": 136.91425 },
"mapView": { "west": 136.91076, "south": 37.08727, "east": 136.91688, "north": 37.09136 }
}
-
subblock
Yo-80 Wakuramachi, Nanao-shi, Ishikawa, Japan:
{
"title": "Yo-80 Wakuramachi, Nanao-shi, Ishikawa, Japan",
"id": "here:xs1:pointaddress:15349663",
"resultType": "addressBlock",
"addressBlockType": "subblock",
"address": {
"label": "Yo-80 Wakuramachi, Nanao-shi, Ishikawa, Japan",
"countryCode": "JPN",
"countryName": "Japan",
"state": "Ishikawa",
"city": "Nanao-shi",
"subdistrict": "Wakuramachi",
"block": "Yo",
"subblock": "80"
},
"position": { "lat": 37.09006, "lng": 136.91445 }
}
Endpoints returning addressBlockType
results: /discover
, /autosuggest
, /lookup
, /browse
, /geocode
, /revgeocode
House number
houseNumber
results are address results containing house-level address details.
Results of type houseNumber
have an additional field houseNumberType
that further defines results of types: interpolated
, PA
PA
stands for "point address" and denotes a very accurate position for the house. A point address represents an individual address as a point object. Point addresses are coming from trusted sources. We can say with high certainty that the address exists and at what position.
interpolated
results are slightly less accurate, but are based on a highly optimized interpolation algorithm. These are approximate positions as a result of a linear interpolation based on address ranges. Address ranges, especially in the USA, are typical per block. For interpolated addresses, we cannot say with confidence that the address exists in reality. But the interpolation provides a good location approximation that brings people in most use cases close to the target location.
WARNING
New houseNumberType
values can get added to the list without further notice. Applications using HERE Geocoding and Search must not assume the list is fixed.
Examples of results for each houseNumberType
value:
-
PA
Invalidenstraße 116, 10115 Berlin, Germany:
{
"title": "Invalidenstraße 116, 10115 Berlin, Germany",
"id": "here:af:streetsection:tVuvjJYhO86yd5jk1cmzNB:CgcIBCCE59BeEAEaAzExNihk",
"resultType": "houseNumber",
"houseNumberType": "PA",
"address": {
"label": "Invalidenstraße 116, 10115 Berlin, Germany",
"countryCode": "DEU",
"countryName": "Germany",
"stateCode": "BE",
"state": "Berlin",
"countyCode": "B",
"county": "Berlin",
"city": "Berlin",
"district": "Mitte",
"street": "Invalidenstraße",
"postalCode": "10115",
"houseNumber": "116"
},
"position": { "lat": 52.53086, "lng": 13.38469 },
"access": [{ "lat": 52.531, "lng": 13.38461 }],
"mapView": { "west": 13.374, "south": 52.5279, "east": 13.39892, "north": 52.53262 }
}
A houseNumber
result contains two types of coordinates. One is the access point (or navigation coordinates), which is the point to start or end a drive. The other point is the position or display point. In case of point addresses this point varies per source and country. The point can be the rooftop point, a point close to the building entry, or a point close to the building, driveway or parking lot that belongs to the building.
-
interpolated
32 Kings Road, Aylesbury, HP21 7RR, England:
{
"title": "32 Kings Road, Aylesbury, HP21 7RR, England",
"id": "here:af:streetsection:i9hvb4V431Jy2My7jXGrqD:EAIaAjMyKGQ",
"resultType": "houseNumber",
"houseNumberType": "interpolated",
"address": {
"label": "32 Kings Road, Aylesbury, HP21 7RR, England",
"countryCode": "GBR",
"countryName": "England",
"countyCode": "BKM",
"county": "Buckinghamshire",
"city": "Aylesbury",
"district": "Aylesbury",
"street": "Kings Road",
"postalCode": "HP21 7RR",
"houseNumber": "32"
},
"position": { "lat": 51.81521, "lng": -0.80388 },
"access": [{ "lat": 51.81509, "lng": -0.80396 }],
"mapView": { "west": -0.80415, "south": 51.81439, "east": -0.80142, "north": 51.81515 }
}
The access point of an interpolated address result is calculated based on the address range and the road geometry. The position (display) point is pre-configured offset from the street geometry.
-
PA
with building
information
A point address result may also include a building name. The building name is a textual address that represents a building or property name. It may be an alternative to a house number or may be in addition to a house number. HERE Geocoding and Search returns building names only for the houseNumber
results with the houseNumberType
PA
and for place
results if their address includes a building name.
HERE Geocoding and Search includes the building name as an individual field building
into the address
block and to the result item title
and address label
.
Rowes Arcade, 235 Edward St, Brisbane City QLD 4000, Australia:
{
"items": [
{
"title": "Rowes Arcade, 235 Edward St, Brisbane City QLD 4000, Australia",
"id": "here:af:streetsection:0F0TpRZ0MvzcapjbTh.5eD:CggIBCDjguazARABGgMyMzUiDFJvd2VzIEFyY2FkZQ",
"resultType": "houseNumber",
"houseNumberType": "PA",
"address": {
"label": "Rowes Arcade, 235 Edward St, Brisbane City QLD 4000, Australia",
"countryCode": "AUS",
"countryName": "Australia",
"stateCode": "QLD",
"state": "Queensland",
"city": "Brisbane",
"district": "Brisbane City",
"street": "Edward St",
"postalCode": "4000",
"houseNumber": "235",
"building": "Rowes Arcade"
},
"position": { "lat": -27.46794, "lng": 153.02697 },
"access": [{ "lat": -27.46812, "lng": 153.02676 }],
"mapView": { "west": 153.02596, "south": -27.46884, "east": 153.02798, "north": -27.46704 },
}
]
}
WARNING
HERE Geocoding and Search currently includes building names into the response and recognizes it as part of the query. But it does not allow to search for an address based on building name only. The query shall contain other detailed address information, such as house number in conjunction with street name or, in case of IRL and SGP, detailed postal code.
Endpoints returning houseNumberType
results: /discover
, /autosuggest
, /lookup
, /geocode
, /autocomplete
, /revgeocode
Street
Result type street
has no further subdivision.
For example, Avenue des Champs-Élysées, 75008 Paris, France:
{
"title": "Avenue des Champs-Élysées, 75008 Paris, France",
"id": "here:af:street:D0.fKrXcM4xmEKKVsiuq5C",
"resultType": "street",
"address": {
"label": "Avenue des Champs-Élysées, 75008 Paris, France",
"countryCode": "FRA",
"countryName": "France",
"stateCode": "IDF",
"state": "Ile-de-France",
"county": "Paris",
"city": "Paris",
"district": "8e Arrondissement",
"street": "Avenue des Champs-Élysées",
"postalCode": "75008"
},
"position": { "lat": 48.86951, "lng": 2.30846 },
"mapView": { "west": 2.29582, "south": 48.86417, "east": 2.32067, "north": 48.87353 }
}
Endpoints returning street
results: /discover
, /autosuggest
, /lookup
, /browse
, /geocode
, /autocomplete
, /revgeocode
Streets intersection
Result type intersection
has no further subdivision.
For example, Friedrichstraße & Unter den Linden, 10117 Berlin, Germany:
{
"title": "Friedrichstraße & Unter den Linden, 10117 Berlin, Germany",
"id": "here:cm:node:61050828",
"resultType": "intersection",
"address": {
"label": "Friedrichstraße & Unter den Linden, 10117 Berlin, Germany",
"countryCode": "DEU",
"countryName": "Germany",
"stateCode": "BE",
"state": "Berlin",
"countyCode": "B",
"county": "Berlin",
"city": "Berlin",
"district": "Mitte",
"streets": ["Friedrichstraße", "Unter den Linden"],
"postalCode": "10117"
},
"position": { "lat": 52.5169, "lng": 13.38883 },
"mapView": { "west": 13.38698, "south": 52.51578, "east": 13.39068, "north": 52.51802 }
}
Endpoints returning intersection
results: /discover
, /autosuggest
, /lookup
, /geocode
, /autocomplete
Postal code point
Result type postalCodePoint
has no further subdivision. Postal code point results can be expected in the following countries: Canada, Great Britain, The Netherlands, United States Of America. A few examples:
- H3R 3B5 Churchill Rd, Mt Royal, QC, Canada
{
"title": "H3R 3B5 Chemin Churchill, Mont-Royal, QC, Canada",
"id": "here:af:streetsection:35DkO-tTO6MAMBjEYFROWB:EAMyB2gzcnwzYjU:EAMyB2gzcnwzYjU",
"resultType": "postalCodePoint",
"address": {
"label": "H3R 3B5 Chemin Churchill, Mont-Royal, QC, Canada",
"countryCode": "CAN",
"countryName": "Canada",
"stateCode": "QC",
"state": "Québec",
"county": "Montréal",
"city": "Mont-Royal",
"street": "Chemin Churchill",
"postalCode": "H3R 3B5"
},
"position": { "lat": 45.51202, "lng": -73.63894 },
"mapView": { "west": -73.64054, "south": 45.5109, "east": -73.63734, "north": 45.51314 }
}
- EC2Y 5HN London Wall, London, United Kingdom
{
"title": "EC2Y 5HN London Wall, London, England",
"id": "here:af:streetsection:FRsFWpGlT-EcxVmUdaz4ZC:EAMyCGVjMnl8NWhu",
"resultType": "postalCodePoint",
"address": {
"label": "EC2Y 5HN London Wall, London, England",
"countryCode": "GBR",
"countryName": "England",
"countyCode": "LDN",
"county": "London",
"city": "London",
"district": "City of London",
"street": "London Wall",
"postalCode": "EC2Y 5HN"
},
"position": { "lat": 51.5176, "lng": -0.09613 },
"mapView": { "west": -0.09794, "south": 51.51648, "east": -0.09432, "north": 51.51872 }
}
- Westsingel 3811 BB, Amersfoort, Nederland
{
"title": "EC2Y 5HN London Wall, London, England",
"id": "here:af:streetsection:FRsFWpGlT-EcxVmUdaz4ZC:EAMyCGVjMnl8NWhu",
"resultType": "postalCodePoint",
"address": {
"label": "EC2Y 5HN London Wall, London, England",
"countryCode": "GBR",
"countryName": "England",
"countyCode": "LDN",
"county": "London",
"city": "London",
"district": "City of London",
"street": "London Wall",
"postalCode": "EC2Y 5HN"
},
"position": { "lat": 51.5176, "lng": -0.09613 },
"mapView": { "west": -0.09794, "south": 51.51648, "east": -0.09432, "north": 51.51872 }
}
- 94115-1234 Broadway, San Francisco, CA, United States
{
"title": "EC2Y 5HN London Wall, London, England",
"id": "here:af:streetsection:FRsFWpGlT-EcxVmUdaz4ZC:EAMyCGVjMnl8NWhu",
"resultType": "postalCodePoint",
"address": {
"label": "EC2Y 5HN London Wall, London, England",
"countryCode": "GBR",
"countryName": "England",
"countyCode": "LDN",
"county": "London",
"city": "London",
"district": "City of London",
"street": "London Wall",
"postalCode": "EC2Y 5HN"
},
"position": { "lat": 51.5176, "lng": -0.09613 },
"mapView": { "west": -0.09794, "south": 51.51648, "east": -0.09432, "north": 51.51872 }
}
Endpoints returning postalCodePoint
results: /discover
, /autosuggest
, /lookup
, /geocode
, /autocomplete
, /revgeocode