Geocode an area

This tutorial demonstrates how to find geo-coordinates of an area.

Procedure

You can also use the/geocode endpoint to find geo-coordinates of an area, such as city, district of a city, postal code, county, state or country. The geo-coordinates are a routing destination for this area. In the case of administrative areas, it can be a 'well-known' street, the main railway station, or some other significant road that allows autos.

For example, a free-form text query to return geo-coordinates of the German capital Berlin can be formulated with the following:

GET https://geocode.search.hereapi.com/v1/
    geocode
    ?q=Berlin
    &apiKey={YOUR_API_KEY}

The following parameters are used:

• q - Enter a free-text query.
• 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 looks like the following:

{
  "items": [
    {
      "title": "Berlin, Deutschland",
      "id": "here:cm:namedplace:20187403",
      "resultType": "locality",
      "localityType": "city",
      "address": {
        "label": "Berlin, Deutschland",
        "countryCode": "DEU",
        "countryName": "Deutschland",
        "stateCode": "BE",
        "state": "Berlin",
        "countyCode": "B",
        "county": "Berlin",
        "city": "Berlin",
        "postalCode": "10117"
      },
      "position": {
        "lat": 52.51604,
        "lng": 13.37691
      },
      "mapView": {
        "west": 13.08835,
        "south": 52.33812,
        "east": 13.761,
        "north": 52.6755
      },
      "scoring": {
        "queryScore": 1,
        "fieldScore": {
          "city": 1
        }
      }
    }
  ]
}

An area results include the following high-level elements:

• resultType - locality or administrativeArea
• localityType - type of the locality, returned if resultType is locality
  • postalCode
  • city
  • district
  • subdistrict
• administrativeAreaType - type of the administrative area, returned if resultType is administrativeArea
  • country
  • state
  • county
• title – the representative string of the area name
• address - the detailed administrative structure of the area
• position - a representative geo-position (WGS 84) of the result. This is to be used to display the result on a map and to access the result
• 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 end user application to accept or reject the results depending on how “expensive” is the mistake for their use case.

Note that access position is not included in the area result.

Additional information

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