Geocode an address

This tutorial demonstrates how to use a text query to return geo-coordinates.

Procedure

A free-form text query to return geo-coordinates for address 240 Washington St., Boston is formulated with the following:

GET https://geocode.search.hereapi.com/v1/
    geocode
    ?q=240+Washington+St.%2C+Boston
    &apiKey={YOUR_API_KEY}

The following parameters are used:

• q - Enter a free-text query.
• apiKey - Your API key.

The response to the above request looks like the following:

{
  "items": [
    {
      "title": "240 Washington St, Boston, MA 02108-4603, United States",
      "id": "here:af:streetsection:YCY1nQWrJ5eBrHv075VVOD:CggIBCDns4LfAhABGgMyNDAoZA",
      "resultType": "houseNumber",
      "houseNumberType": "PA",
      "address": {
        "label": "240 Washington St, Boston, MA 02108-4603, United States",
        "countryCode": "USA",
        "countryName": "United States",
        "stateCode": "MA",
        "state": "Massachusetts",
        "county": "Suffolk",
        "city": "Boston",
        "district": "Downtown Boston",
        "street": "Washington St",
        "postalCode": "02108-4603",
        "houseNumber": "240"
      },
      "position": {
        "lat": 42.35814,
        "lng": -71.05765
      },
      "access": [
        {
          "lat": 42.35815,
          "lng": -71.05788
        }
      ],
      "mapView": {
        "west": -71.05887,
        "south": 42.35724,
        "east": -71.05643,
        "north": 42.35904
      },
      "scoring": {
        "queryScore": 1,
        "fieldScore": {
          "city": 1,
          "streets": [
            1
          ],
          "houseNumber": 1
        }
      }
    },
    {
      "title": "240 Washington St, Boston, MA 02135-3508, United States",
      "id": "here:af:streetsection:6SnFDsUujYAamxhLX-Vr1D:CgcIBCDRnLAhEAEaAzI0MChk",
      "resultType": "houseNumber",
      "houseNumberType": "PA",
      "address": {
        "label": "240 Washington St, Boston, MA 02135-3508, United States",
        "countryCode": "USA",
        "countryName": "United States",
        "stateCode": "MA",
        "state": "Massachusetts",
        "county": "Suffolk",
        "city": "Boston",
        "district": "Brighton Center",
        "street": "Washington St",
        "postalCode": "02135-3508",
        "houseNumber": "240"
      },
      "position": {
        "lat": 42.34754,
        "lng": -71.14943
      },
      "access": [
        {
          "lat": 42.34765,
          "lng": -71.14925
        }
      ],
      "mapView": {
        "west": -71.15065,
        "south": 42.34664,
        "east": -71.14821,
        "north": 42.34844
      },
      "scoring": {
        "queryScore": 1,
        "fieldScore": {
          "city": 1,
          "streets": [
            1
          ],
          "houseNumber": 1
        }
      }
    }
  ]
}

The query is ambiguous - in Boston there are two streets with this name and both of them have house number 240. Therefore, the response includes two results with different locations, postal codes and district names.

An address result includes the following high-level elements:

• resultType - houseNumber
• houseNumberType - type of address data, returned if resultTypeis houseNumber
  • PA - Point Address, location matches as an individual point object
  • interpolated - location was interpolated from an address range
• title – a representative string for the result. In the case of address, it is the complete postal address string
• address - the detailed address of the result
• position - a representative geo-position (WGS 84) of the result. This is to be used to locate or display the result on a map
• access - the geo-position of the access to the result (for instance the entrance)
• mapView - bounding box of the location optimized for display
• id - the identifier of the result object. Its value can be used to retrieve the very same object through the /lookup endpoint.
• scoring - the /geocode endpoint returns scoring information, which indicates for each result how good it matches to the original query. This can be used by the customer application to accept or reject the results depending on how “expensive” is the mistake for their use case.

Additional information

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