Geocode a place

This tutorial demonstrates how to find geo-coordinates of a known place.

Procedure

The /geocode endpoint also supports finding the geo-coordinates of a known place. This allows, for instance, geocoding business addresses, which include business names, the same way as residential addresses.

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

GET https://geocode.search.hereapi.com/v1/
    geocode
    ?q=Starbucks%2C+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 query is not ambiguous - in Boston there are two streets with this name and both of them have house number 240. One is in the Boston downtown, the other one in a Boston neighborhood. But Starbucks is located only by this address in the Boston downtown.

The response to the above request consists of a single result and looks like the following:

{
  "items": [
    {
      "title": "Starbucks",
      "id": "here:pds:place:840drt2z-d9bbdad5d12d410fa597ff9a57f0eef4:CggIBCDns4LfAhABGgMyNDA",
      "resultType": "place",
      "address": {
        "label": "Starbucks, 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
      },
      "categories": [
        {
          "id": "100-1100-0010",
          "name": "Coffee Shop",
          "primary": true
        }
      ],
      "foodTypes": [
        {
          "id": "800-058",
          "name": "Snacks & Beverages",
          "primary": true
        }
      ],
      "scoring": {
        "queryScore": 1,
        "fieldScore": {
          "city": 1,
          "streets": [
            1
          ],
          "houseNumber": 1,
          "placeName": 1
        }
      }
    }
  ]
}

A place result includes the following high-level elements:

• resultType - place
• title – place name
• address - the detailed address of the result, including the complete postal address of the place
• position - a representative geo-position (WGS 84) of the result. This is to be used to 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.
• categories - a list of category ids for place results
• foodTypes - a list of food-type ids for place results preparing/serving food
• 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 end user application to accept or reject the results depending on how “expensive” is the mistake for their use case.

Note that the /geocode endpoint only allows place results if the request provides reasonable location context, such as complete street address, spatial reference or at least partial : street name, locality name or postal code. Placing the name without any locality context is not specific enough. For example, query McDonald, Germany cannot be resolved to a specific location. Exception - national importance places. A query such as Eiffel Tower is specific enough for the /geocode endpoint to return the place result.

Additional information

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