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` `MPA (RESTRICTED)`
`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

📘
Note
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

📘
Note
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 addressing systems in Japan and in some other countries. The results have an additional field addressBlockType that further defines results of types: block, subblock.

Countries in which HERE Geocoding and Search supports results of type addressBlock:

Japan,
Indonesia - addressBlockType=block; /geocode and /lookup endpoints.

📘
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, MPA

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.

MPA stands for "micro point address" and represents a secondary address for a point address; for example, building, floor (level) and suite (unit). In comparison with a point address, a micro point address has greater address detail and higher coordinate accuracy. This result type is only returned by geocode endpoint if 'with=MPA' parameter is set in the request ("RESTRICTED" feature - see privilege) or by lookup endpoint as a result of lookup by id. Currently HERE Geocoding and Search supports micro point addresses in the following countries: AUS, AUT, CAN, NZL, USA (with the territory of PRI).

📘
Note
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.

MPA

710/84 Northbourne Ave, Braddon ACT 2612, Australia:

{
"title": "710/84 Northbourne Ave, Braddon ACT 2612, Australia",
"id": "here:af:streetsection:.W90ivJgffuB3CYZPYn6fD:ChYIBCCymKydATIMCggIFCDlwrqiAhAEEAEaAjg0",
"language": "en",
"resultType": "houseNumber",
"houseNumberType": "MPA",
"address": {
  "label": "710/84 Northbourne Ave, Braddon ACT 2612, Australia",
  "countryCode": "AUS",
  "countryName": "Australia",
  "stateCode": "ACT",
  "state": "Australian Capital Territory",
  "city": "Canberra",
  "district": "Braddon",
  "street": "Northbourne Ave",
  "postalCode": "2612",
  "houseNumber": "84",
  "unit": "710"
},
"position": { "lat": -35.27422, "lng": 149.13065 },
"access": [{ "lat": -35.27416, "lng": 149.13013 }],
"mapView": { "west": 149.12989, "south": -35.27575, "east": 149.13233, "north": -35.26053 }
}

An MPA result contains the same information as a PA result, and it also includes secondary unit information in the unit field, as well as in the result title and address label. It may include building, floor (level), and suite (unit) details. An MPA may share the same position and access coordinates as the PA it belongs to but in many cases, the MPA has more accurate position and access coordinates than those of the PA.

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 },
  }
]
}

📘
Note
HERE Geocoding and Search currently includes building names into the response for all endpoints. The /geocode endpoint also offers comprehensive support for building names search. You can use the the /geocode endpoint to search for locations using building names. Note that searching for building names is not yet supported by other endpoints, including Autocomplete, Autosuggest, and Discover Search.

Endpoints returning houseNumberType results with house number type PA or interpolated: /discover, /autosuggest, /lookup, /geocode, /autocomplete, /revgeocode

Endpoints returning houseNumberType results with house number type MPA: /lookup, /geocode - the last one only if 'with=MPA' parameter is set in the request.

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, Ireland, Israel, Isle of Man, Malaysia, the Netherlands, Portugal, Singapore, Taiwan, the United Kingdom, and the United States of America with the territory of Puerto Rico (including ZIP+4 and three types of ZIP codes: those unique to an address, PO Box zip codes, and military postal codes ZIP codes). 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": "Westsingel 3811 BB, Amersfoort, Nederland",
    "id": "here:af:streetsection:vcV6RFNSviDyTwaBumO8qC:EAMyBzM4MTF8YmI:EAMyBzM4MTF8YmI",
    "resultType": "postalCodePoint",
    "address": {
        "label": "Westsingel 3811 BB, Amersfoort, Nederland",
        "countryCode": "NLD",
        "countryName": "Nederland",
        "stateCode": "UT",
        "state": "Utrecht",
        "county": "Amersfoort",
        "city": "Amersfoort",
        "street": "Westsingel",
        "postalCode": "3811 BB"
    },
    "position": { "lat": 52.1567, "lng": 5.38567 },
    "mapView": { "west": 5.38384, "south": 52.15558, "east": 5.3875, "north": 52.15782 }
}

94115-1234 Broadway, San Francisco, CA, United States

{
    "title": "94115-1234 Broadway, San Francisco, CA, United States",
    "id": "here:af:streetsection:QfdUDbG7suRcC.PvvAfEHB:EAMyCjk0MTE1fDEyMzQ:EAMyCjk0MTE1fDEyMzQ",
    "resultType": "postalCodePoint",
    "address": {
        "label": "94115-1234 Broadway, San Francisco, CA, United States",
        "countryCode": "USA",
        "countryName": "United States",
        "stateCode": "CA",
        "state": "California",
        "county": "San Francisco",
        "city": "San Francisco",
        "district": "Pacific Heights",
        "street": "Broadway",
        "postalCode": "94115-1234"
    },
    "position": { "lat": 37.79424, "lng": -122.43578 },
    "mapView": { "west": -122.4372, "south": 37.79312, "east": -122.43436, "north": 37.79536 }
}

Endpoints returning postalCodePoint results: /discover, /autosuggest, /lookup, /geocode, /autocomplete, /revgeocode