Result types

HERE Geocoding and Search provide customers a flexible way to retrieve relevant results for textual queries.

All results are typed: Each result item contains a response element resultType with a well-defined value.

There are currently 9 values in this resultType , which is an enum of: place, locality, street, houseNumber, administrativeArea, addressBlock, intersection, postalCodePoint, chainQuery, categoryQuery.

WARNING

New resultType values can get added to the list without further notice. Applications using HERE Geocoding and Search must not assume the list is fixed. For instance intersection and postalCodePoint are newly introduced result types.

Following chapters are grouping all result types into 3 main kinds:

a place (a "point of interest" in the GIS literature)
an address related result (a city, a street, a house, ...)
a query suggestion

Place results

A place result represents a point of interest: A point feature with a name, a position, an address and a list of categories defining the functionality characterizing the point. A place can be as various as a restaurant, an EV charging station, an airport, a stadium, etc.

HERE Geocoding and Search place results can be identified through the place value of the resultType response element.

The sub-type field categories contains a list of IDs referencing the different functionality of the location. For restaurant results, the sub-type foodTypes contains a list of IDs for the cuisines that the restaurant offers.

For example, Glacier Vanille Noire (in Marseille):

{
    "title": "Glacier Vanille Noire",
    "id": "here:pds:place:250jx7ps-8f300d0f8ec60e31fb76a3d22f00f18f",
    "resultType": "place",
    "address": {
        "label": "Glacier Vanille Noire, 13 Rue Caisserie, 13002 Marseille, France",
        "countryCode": "FRA",
        "countryName": "France",
        "stateCode": "PAC",
        "state": "Provence-Alpes-Cote d'Azur",
        "county": "Bouches-du-Rhône",
        "city": "Marseille",
        "district": "2e Arrondissement",
        "street": "Rue Caisserie",
        "postalCode": "13002",
        "houseNumber": "13"
    },
    "position": { "lat": 43.2972, "lng": 5.36871 },
    "access": [{ "lat": 43.29723, "lng": 5.36868 }],
    "categories": [
        { "id": "100-1000-0000", "name": "Restaurant", "primary": true },
        { "id": "300-3000-0000", "name": "Landmark-Attraction" },
        { "id": "600-6300-0064", "name": "Food/Beverage Specialty Store" },
        { "id": "600-6300-0364", "name": "Dairy Goods" },
        { "id": "700-7200-0253", "name": "Catering & Other Food Services" }
    ],
    "foodTypes": [{ "id": "800-063", "name": "Ice Cream", "primary": true }],
    "contacts": [{
        "phone": [{ "value": "+33777336819" }],
        "www": [{
            "value": "http://www.vanillenoire.com",
            "categories": [{ "id": "100-1000-0000" }, { "id": "300-3000-0000" }, { "id": "700-7200-0253" }]
        }],
        "email": [{
            "value": "nicolas@vanillenoire.com",
            "categories": [{ "id": "100-1000-0000" }, { "id": "300-3000-0000" }]
        }]
    }],
    "openingHours": [{
        "categories": [{ "id": "100-1000-0000" }, { "id": "300-3000-0000" }, { "id": "600-6300-0064" }],
        "text": ["Mon-Sun: 13:00 - 19:00"],
        "isOpen": true,
        "structured":
            [{ "start": "T130000", "duration": "PT06H00M", "recurrence": "FREQ:DAILY;BYDAY:MO,TU,WE,TH,FR,SA,SU" }]}
    ],
    "references": [
        { "supplier": { "id": "core" }, "id": "1149014863" },
        { "supplier": { "id": "tripadvisor" }, "id": "6596803" },
        { "supplier": { "id": "yelp" }, "id": "LNW8pvVArKkCYg_SM0WfXQ" }
    ]
}

Endpoints returning place results: /discover, /autosuggest, /lookup, /browse, /geocode /revgeocode

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:

{
  "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 (in Berlin):

{
  "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 (in Boston):

{
  "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 (in Gole Market district of New Delhi):

{
  "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

California:

{
  "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 (in 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 block in Wakuramachi sub-district of Nanao-Shi city:

{
  "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

subblock 80 of the Yo block:

{
  "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,

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. interpolated results are slightly less accurate, but are based on a highly optimized interpolation algorithm.

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

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

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

Street

Result type street has no further subdivision.

For example, Avenue des Champs-Elysees (in Paris):

{
    "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 (in Berlin):

{
    "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.

For example, London Wall:

{
    "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

Query suggestions

Query suggestions are meant to be used by application developers to build more precise follow-up queries, especially when the query entered by the end-user is incomplete.

Query suggestions are

either words to be picked up by the end-user to replace the last entered incomplete query token
or follow-up query URLs to be picked up by the end-user to get more precise results

The first ones are isolated in a separate list. They are not results per-se, but just words. These query last token suggestions are described in Autosuggest endpoint Query Term Completion chapter.

The second ones are real results ranked together with other types in Autosuggest result set. Their result type is either categoryQuery or chainQuery.

The follow-up queries only return place typed items, either of a particular chain or a particular category. For example:

categoryQuery

restaurants query suggestion:

{
  "title": "restaurant",
  "id": "here:cm:ontology:restaurant",
  "resultType": "categoryQuery",
  "href": "https://autosuggest.search.hereapi.com/v1/discover?q=restaurant&_ontology=restaurant&lang=en&at=52.93175%2C12.77165",
  "highlights": ...
}

chainQuery

Starbucks query suggestion:

{
  "title": "Starbucks",
  "id": "here:cm:ontology:starbucks",
  "resultType": "chainQuery",
  "href": "https://autosuggest.search.hereapi.com/v1/discover?q=Starbucks&_ontology=starbucks&lang=en-US&at=48.37773%2C12.03539",
  "highlights": ...
}

Related endpoint: /autosuggest

Result Types

Result types

WARNING

Place results

Locality

WARNING

Administrative area

WARNING

Address block

WARNING

House number

WARNING

Street

Streets intersection

Postal code point

Query suggestions

results matching ""

No results matching ""

Developer

Result types

WARNING

Place results

Address related results

Locality

WARNING

Administrative area

WARNING

Address block

WARNING

House number

WARNING

Street

Streets intersection

Postal code point

Query suggestions

results matching ""

No results matching ""

Developer