Using 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.

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/geocode parameters, see: API Reference.