Limit results to specific types
This tutorial demonstrates the /autocomplete
endpoint optional parameter types, which allow limiting the results to specific types.
Procedure
The /autocomplete
endpoint has an optional parameter types
which allows limiting the results to specific types.
Values of the result type filter, supported by the /autocomplete
endpoint:
-
city
- restricting results to resultType
: locality
and localityType
: city
-
postalCode
- restricting results to resultType
: locality
and localityType
: postalCode
. Note that result type filter postalCode
covers only regular postal codes such as in Germany or ZIP codes in the USA. "High Precision" postal codes, such as postal codes in the UK or USA postal codes with ZIP+4 extensions have resultType
: postalCodePoint
and are not included into postalCode
result type filter. -
area
- restricting results to result types locality
or administrativeArea
including all the sub-types
Let's take the query Alexand
with country limited to DEU
as an example. Without any result type restriction, the /autocomplete
endpoint returns results of different types, including street
and locality
:
GET https://autocomplete.search.hereapi.com/v1/
autocomplete
?q=Alexand
&in=countryCode%3ADEU
&limit=2
&apiKey={YOUR_API_KEY}
The following parameters are used:
- q - Enter a free-text query.
- in - Search within a geographic area. Results will be returned if they are located within the specified area.
- limit - Maximum number of results to be returned.
- apiKey - Your API key.
The first two results are of type street
in Berlin:
{
"items": [
{
"title": "Deutschland, Berlin, Alexanderstraße",
"id": "here:af:street:nJn6GSK6GnY2ogUvJEbxgC",
"language": "de",
"resultType": "street",
"address": {
"label": "Alexanderstraße, 10178 Berlin, Deutschland",
"countryCode": "DEU",
"countryName": "Deutschland",
"stateCode": "BE",
"state": "Berlin",
"countyCode": "B",
"county": "Berlin",
"city": "Berlin",
"district": "Mitte",
"street": "Alexanderstraße",
"postalCode": "10178"
},
"highlights": {
"title": [
{
"start": 21,
"end": 28
}
],
"address": {
"label": [
{
"start": 0,
"end": 7
}
],
"street": [
{
"start": 0,
"end": 7
}
]
}
}
},
{
"title": "Deutschland, Berlin, Tunnel Alexanderplatz",
"id": "here:af:street:8D.iFHvj6zgTiCN1V583EC",
"language": "de",
"resultType": "street",
"address": {
"label": "Tunnel Alexanderplatz, 10178 Berlin, Deutschland",
"countryCode": "DEU",
"countryName": "Deutschland",
"stateCode": "BE",
"state": "Berlin",
"countyCode": "B",
"county": "Berlin",
"city": "Berlin",
"district": "Mitte",
"street": "Tunnel Alexanderplatz",
"postalCode": "10178"
},
"highlights": {
"title": [
{
"start": 28,
"end": 35
}
],
"address": {
"label": [
{
"start": 7,
"end": 14
}
],
"street": [
{
"start": 7,
"end": 14
}
]
}
}
}
]
}
If the end user is not interested in street or address results, the customer application can restrict result types to area
:
GET https://autocomplete.search.hereapi.com/v1/
autocomplete
?q=Alexand
&in=countryCode%3ADEU
&limit=2
&types=area
&apiKey={YOUR_API_KEY}
The first result is a district of city Oldenburg and the second result is a small town in Bavaria:
{
"items": [
{
"title": "Deutschland, 26127, Oldenburg (Oldb.), Alexandersfeld",
"id": "here:cm:namedplace:20155909",
"language": "de",
"resultType": "locality",
"localityType": "district",
"address": {
"label": "Alexandersfeld, Oldenburg (Oldb.), Niedersachsen, Deutschland",
"countryCode": "DEU",
"countryName": "Deutschland",
"stateCode": "NI",
"state": "Niedersachsen",
"countyCode": "OL",
"county": "Oldenburg (Oldb.)",
"city": "Oldenburg (Oldb.)",
"district": "Alexandersfeld",
"postalCode": "26127"
},
"highlights": {
"title": [
{
"start": 39,
"end": 46
}
],
"address": {
"label": [
{
"start": 0,
"end": 7
}
],
"district": [
{
"start": 0,
"end": 7
}
]
}
}
},
{
"title": "Deutschland, 95680, Bad Alexandersbad",
"id": "here:cm:namedplace:20182868",
"language": "de",
"resultType": "locality",
"localityType": "city",
"address": {
"label": "Bad Alexandersbad, Bayern, Deutschland",
"countryCode": "DEU",
"countryName": "Deutschland",
"stateCode": "BY",
"state": "Bayern",
"countyCode": "WUN",
"county": "Wunsiedel im Fichtelgebirge",
"city": "Bad Alexandersbad",
"postalCode": "95680"
},
"highlights": {
"title": [
{
"start": 24,
"end": 31
}
],
"address": {
"label": [
{
"start": 4,
"end": 11
}
],
"city": [
{
"start": 4,
"end": 11
}
]
}
}
}
]
}
If the end user is looking only for cities or towns, the customer application can restrict result types to city
only instead of area
:
GET https://autocomplete.search.hereapi.com/v1/
autocomplete
?q=Alexand
&in=countryCode%3ADEU
&limit=2
&types=city
&apiKey={YOUR_API_KEY}
The /autocomplete
endpoint returns now only the small town in Bavaria:
{
"items": [
{
"title": "Deutschland, 95680, Bad Alexandersbad",
"id": "here:cm:namedplace:20182868",
"language": "de",
"resultType": "locality",
"localityType": "city",
"address": {
"label": "Bad Alexandersbad, Bayern, Deutschland",
"countryCode": "DEU",
"countryName": "Deutschland",
"stateCode": "BY",
"state": "Bayern",
"countyCode": "WUN",
"county": "Wunsiedel im Fichtelgebirge",
"city": "Bad Alexandersbad",
"postalCode": "95680"
},
"highlights": {
"title": [
{
"start": 24,
"end": 31
}
],
"address": {
"label": [
{
"start": 4,
"end": 11
}
],
"city": [
{
"start": 4,
"end": 11
}
]
}
}
}
]
}
For types=postalCode
, the /autocomplete
endpoint expects as an input a complete or partial postal code. For the query Alexand
with types=postalCode
it will return no result.
For more information about/autocomplete
parameters, see: API Reference.
For an overview of types
filter support by different endpoints check: Filtering results by their types.