Geocode

The /geocode endpoint is used to find the geo-coordinates of a known address, place, locality or administrative area, even if the query is incomplete or partly incorrect. It also returns a complete postal address string and address details.

For example, a free-form text query for address 5 Rue Daunou, 75000 Paris, France is formulated with the following request:

GET https://geocode.search.hereapi.com/v1/
    geocode
    ?q=5+Rue+Daunou%2C+75000+Paris%2C+France
    &apiKey={YOUR_API_KEY}

The postal code in the query is incorrect due to a user mistake.

The response to the above request looks like the following:

{
  "items": [
    {
      "title": "5 Rue Daunou, 75002 Paris, France",
      "id": "here:af:streetsection:bI4Le6cyA.1mlQyLunYpjC:CggIBCCi-9SPARABGgE1KGQ",
      "resultType": "houseNumber",
      "houseNumberType": "PA",
      "address": {
        "label": "5 Rue Daunou, 75002 Paris, France",
        "countryCode": "FRA",
        "countryName": "France",
        "stateCode": "IDF",
        "state": "Île-de-France",
        "county": "Paris",
        "city": "Paris",
        "district": "2e Arrondissement",
        "street": "Rue Daunou",
        "postalCode": "75002",
        "houseNumber": "5"
      },
      "position": {
        "lat": 48.86926,
        "lng": 2.3321
      },
      "access": [
        {
          "lat": 48.86931,
          "lng": 2.33215
        }
      ],
      "mapView": {
        "west": 2.33073,
        "south": 48.86836,
        "east": 2.33347,
        "north": 48.87016
      },
      "scoring": {
        "queryScore": 0.97,
        "fieldScore": {
          "country": 1,
          "city": 1,
          "streets": [
            1
          ],
          "houseNumber": 1,
          "postalCode": 0.82
        }
      }
    }
  ]
}

The response includes geo-coordinates of the address and complete postal address string with correct postal code.

It delivers the following high-level elements for each result:

• resultType - HERE Geocoding and Search /geocode is able to return items of several types: houseNumber,place, locality, street,
  administrativeArea, addressBlock, intersection, postalCodePoint
• houseNumberType - type of address data (returned only for address results):
  • PA - Point Address, location matches as individual point object
  • interpolated - location was interpolated from an address range
• title – a representative string for the result. In 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 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
• 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
• id - the identifier of the result object. Its value can be used to retrieve the very same object through the /lookup endpoint.

More details about /geocode parameters can be found in the API Reference.