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.

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.