Limit results to specific types
This tutorial demonstrates the /autocomplete
endpoint optional parameter types, which allow limiting the results to specific types. A result type allows you to get specific results based on the following options:
city
postalCode
area
Procedure
The /autocomplete
endpoint has an optional parameter types
which allows limiting the results to specific types.
The following list shows values of the result type filter, which are supported by the /autocomplete
endpoint:
city
- restricting results toresultType
:locality
andlocalityType
:city
postalCode
- restricting results toresultType
:locality
andlocalityType
:postalCode
. Note that result type filterpostalCode
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 haveresultType
:postalCodePoint
and are not included intopostalCode
result type filter.area
- restricting results to result typeslocality
oradministrativeArea
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.
Note
This request uses API key authentication. For more information about authentication options on the HERE platform, see the Identity & Access Management Guide.
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.
Additional information
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.