Limit results to one or several countries

This tutorial demonstrates how the /autocomplete endpoint allows limiting results to one or several countries.

Procedure

This feature is useful to avoid ambiguity and unexpected results when you know that all the addresses are located in a specific country.

For example, one highly relevant result for a global query Paris would be the capital of France. But if the end-user is only interested in address suggestions from Germany, your application can limit the results to Germany by specifying the parameter in=countryCode:DEU

Formulate the query like this:

GET https://autocomplete.search.hereapi.com/v1/
    autocomplete
    ?q=Paris
    &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 that this query includes the parameter limit=2 to limit number of the suggestions. The default limit for /autocomplete is 5. The maximum value for the limit parameter supported by /autocomplete is 20.

Since Paris is a city in France, it does not meet the country filter criteria. Instead the /autocomplete responds with address suggestions from Germany that contain token Paris for example in the street name or district name. One relevant suggestion may be Pariser Platz in Berlin:

{
  "items": [
    {
      "title": "Deutschland, Berlin, Pariser Platz",
      "id": "here:af:street:blZMmLnwtsYaXawaeHWfzC",
      "language": "de",
      "resultType": "street",
      "address": {
        "label": "Pariser Platz, 10117 Berlin, Deutschland",
        "countryCode": "DEU",
        "countryName": "Deutschland",
        "stateCode": "BE",
        "state": "Berlin",
        "countyCode": "B",
        "county": "Berlin",
        "city": "Berlin",
        "street": "Pariser Platz",
        "postalCode": "10117"
      },
      "highlights": {
        "title": [
          {
            "start": 21,
            "end": 26
          }
        ],
        "address": {
          "label": [
            {
              "start": 0,
              "end": 5
            }
          ],
          "street": [
            {
              "start": 0,
              "end": 5
            }
          ]
        }
      }
    },
    {
      "title": "Deutschland, Berlin, Straße der Pariser Kommune",
      "id": "here:af:street:AfkQXa0XADEPA-WZxLPzmB",
      "language": "de",
      "resultType": "street",
      "address": {
        "label": "Straße der Pariser Kommune, 10243 Berlin, Deutschland",
        "countryCode": "DEU",
        "countryName": "Deutschland",
        "stateCode": "BE",
        "state": "Berlin",
        "countyCode": "B",
        "county": "Berlin",
        "city": "Berlin",
        "district": "Friedrichshain",
        "street": "Straße der Pariser Kommune",
        "postalCode": "10243"
      },
      "highlights": {
        "title": [
          {
            "start": 32,
            "end": 37
          }
        ],
        "address": {
          "label": [
            {
              "start": 11,
              "end": 16
            }
          ],
          "street": [
            {
              "start": 11,
              "end": 16
            }
          ]
        }
      }
    }
  ]
}

Additional information

For more information about/autocomplete parameters, see: API Reference.