Limit results to one or several countries

This tutorial demonstrates how the API limits results to one or several countries.

Procedure

The /geocode endpoint allows limiting results to one or several countries. This is useful to avoid ambiguity and unexpected results when you know that all the addresses are located in a specific country.

For example, for the query 20 Victoria St, London the /geocode would return two results - one in England and one in Canada.

If your application only works with addresses in the USA and Canada, you can limit the result by these two countries with parameter in=countryCode:CAN,USA

The query can be formulated with the following:

GET https://geocode.search.hereapi.com/v1/
    geocode
    ?q=20+Victoria+St%2C+London
    &in=countryCode%3ACAN%2CUSA
    &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.
• apiKey - Your API key.

The response to the above request contains a single result in Canada and looks like the following:

{
  "items": [
    {
      "title": "20 Victoria St, London, ON N6A, Canada",
      "id": "here:af:streetsection:YOrVG8JgXxLvp3Qomjb.SB:EAIaAjIwKGQ",
      "resultType": "houseNumber",
      "houseNumberType": "interpolated",
      "address": {
        "label": "20 Victoria St, London, ON N6A, Canada",
        "countryCode": "CAN",
        "countryName": "Canada",
        "stateCode": "ON",
        "state": "Ontario",
        "county": "Middlesex",
        "city": "London",
        "district": "North London",
        "street": "Victoria St",
        "postalCode": "N6A",
        "houseNumber": "20"
      },
      "position": {
        "lat": 43.0009,
        "lng": -81.2681
      },
      "access": [
        {
          "lat": 43.00078,
          "lng": -81.26803
        }
      ],
      "mapView": {
        "west": -81.26933,
        "south": 43,
        "east": -81.26687,
        "north": 43.0018
      },
      "scoring": {
        "queryScore": 1,
        "fieldScore": {
          "city": 1,
          "streets": [
            1
          ],
          "houseNumber": 1
        }
      }
    }
  ]
}

Additional information

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