Limit results using a spatial reference

This tutorial demonstrates how to use a spatial reference.

Procedure

Customer applications can use at to specify the center of the search context expressed as coordinates. Alternatively customer application may use in=circle or in=bbox to limit the results by a circular area or a bounding box. Th in parameter is a hard filter.

For example, one highly relevant result for a global query Paris would be the capital of France. But the end-users located in, for example, Berlin may be more interested to see street results around them, with street names starting from Paris.

Formulate the query like this:

GET https://autocomplete.search.hereapi.com/v1/
    autocomplete
    ?q=Paris
    &at=52.5249445%2C13.3689829
    &limit=2
    &apiKey={YOUR_API_KEY}

The following parameters are used:

• q - Enter a free-text query.
• at - Specify the center of the search context expressed as coordinates.
• limit - Maximum number of results to be returned.
• apiKey - Your API key.

Note this query includes the parameter limit=2 to limit the number of the suggestions. The default limit for /autocomplete is 5. The maximum value for the limit parameter supported by /autocomplete is 20.

The response includes address suggestions for addresses around the specified position in Berlin that contain token Paris in this case in the street name:

{
  "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"
      },
      "distance": 1140,
      "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"
      },
      "distance": 4806,
      "highlights": {
        "title": [
          {
            "start": 32,
            "end": 37
          }
        ],
        "address": {
          "label": [
            {
              "start": 11,
              "end": 16
            }
          ],
          "street": [
            {
              "start": 11,
              "end": 16
            }
          ]
        }
      }
    }
  ]
}

The response for each item in this case contains the field distance, which is the distance in meters from the at position to this result.

Similarly for queries with in parameter limiting results by circular area or bounding box around city Berlin, /autocomplete returns only results within these spatial filters.

GET https://autocomplete.search.hereapi.com/v1/
    autocomplete
    ?q=Paris
    &in=circle%3A52.5161288%2C13.3896019%3Br%3D20000
    &limit=2
    &apiKey={YOUR_API_KEY}

The following parameters are used:

• q - Enter a free-text query.
• in=circle - Search within a geographic area. This is a hard filter. Results will be returned if they are located within the specified circular area.
• limit - Maximum number of results to be returned.
• apiKey - Your API key.

GET https://autocomplete.search.hereapi.com/v1/
    autocomplete
    ?q=Paris
    &in=bbox%3A13.08835%2C52.33812%2C13.761%2C52.6755
    &limit=2
    &apiKey={YOUR_API_KEY}

The following parameters are used:

• q - Enter a free-text query.
• in=bbox - Search within a geographic area. This is a hard filter. Results will be returned if they are located within the specified bounding box.
• limit - Maximum number of results to be returned.
• apiKey - Your API key.

Additional information

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