Use spatial references

This tutorial demonstrates how the API uses a spatial reference.

Procedure

The /geocode endpoint has an optional at parameter which is usually used to set the current location for location-based search. In this case, the city name normally should be omitted from the query.

For example, a free-form text query for address 32 Tremont st, with at position in downtown Boston and the maximum number of results limited to one is formulated with the following:

GET https://geocode.search.hereapi.com/v1/
    geocode
    ?q=32+Tremont+st
    &at=42.358166%2C-71.0563946
    &limit=1
    &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 request uses API key authentication. For more information about authentication options on the HERE platform, see the Identity & Access Management Guide.

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

{
  "items": [
    {
      "title": "32 Tremont St, Boston, MA 02108-3201, United States",
      "id": "here:af:streetsection:bTM9lA13maMMGHDXOCPTRA:CgcIBCC225AkEAEaAjMyKGQ",
      "resultType": "houseNumber",
      "houseNumberType": "PA",
      "address": {
        "label": "32 Tremont St, Boston, MA 02108-3201, United States",
        "countryCode": "USA",
        "countryName": "United States",
        "stateCode": "MA",
        "state": "Massachusetts",
        "county": "Suffolk",
        "city": "Boston",
        "district": "Downtown Boston",
        "street": "Tremont St",
        "postalCode": "02108-3201",
        "houseNumber": "32"
      },
      "position": {
        "lat": 42.35852,
        "lng": -71.05977
      },
      "access": [
        {
          "lat": 42.3586,
          "lng": -71.06
        }
      ],
      "distance": 280,
      "mapView": {
        "west": -71.06099,
        "south": 42.35762,
        "east": -71.05855,
        "north": 42.35942
      },
      "scoring": {
        "queryScore": 1,
        "fieldScore": {
          "streets": [
            1
          ],
          "houseNumber": 1
        }
      }
    }
  ]
}

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.

Additional information

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