Address lookup by postal code (SGP, IRL)

This tutorial demonstrates how to lookup addresses in Singapore (SGP) and Ireland (IRL) using postal codes.

Procedure

The Irish national postcode system, Eircode, assigns a unique postal code for every home and business address. In Singapore, postal codes are also as precise as addresses. In both countries, people can use the postal code to find a specific address and location - without street name, city or neighborhood or even house number. The /geocode endpoint supports this use case. It can find a complete address for a freeform or qualified query, which includes only postal code. This feature is available for these two countries only.

The postal codes should have the following precisions:

• for Singapore: six-digit postal code
• for Ireland: seven characters "Eircode"

For example, the user can find an address "4 Derrynane Gardens, Dublin, County Dublin, D04 WR52, Ireland" by specifying only postal code - either as qualified query:

GET https://geocode.search.hereapi.com/v1/
    geocode
    ?qq=
        postalCode=D04+WR52
    &apiKey={YOUR_API_KEY}

Or as freeform query:

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

The following parameters are used:

• qq - Enter a qualified query. A qualified query is similar to a free-text query, but in a structured manner. It can take multiple sub-parameters, separated by semicolon, allowing to specify different aspects of a query.
• apiKey - Your API key.

In both cases the response is the same. It has only one matched field - postal code. But the result type is the complete address:

{
  "items": [
    {
      "title": "4 Derrynane Gardens, Dublin, County Dublin, D04 WR52, Ireland",
      "id": "here:af:streetsection:xXbhv-RtAOYHP17itm9nPC:CgcIBCCr4K5mEAEaATQ",
      "resultType": "houseNumber",
      "houseNumberType": "PA",
      "address": {
        "label": "4 Derrynane Gardens, Dublin, County Dublin, D04 WR52, Ireland",
        "countryCode": "IRL",
        "countryName": "Ireland",
        "countyCode": "D",
        "county": "County Dublin",
        "city": "Dublin",
        "district": "Dublin 4",
        "street": "Derrynane Gardens",
        "postalCode": "D04 WR52",
        "houseNumber": "4"
      },
      "position": {
        "lat": 53.33782,
        "lng": -6.22906
      },
      "access": [
        {
          "lat": 53.33786,
          "lng": -6.22839
        }
      ],
      "mapView": {
        "west": -6.23057,
        "south": 53.33692,
        "east": -6.22755,
        "north": 53.33872
      },
      "scoring": {
        "queryScore": 1,
        "fieldScore": {
          "postalCode": 1
        }
      }
    }
  ]
}

Postal codes in Singapore consist of six digits and look very similar to postal codes in many other countries. To avoid ambiguity and get the results for postal code only queries, it is recommended to provide additionally either spatial reference with at parameter or the Singapore country name or upper-case country code. Or set country filter to "SGP".

For example, the user can find an address "53 Stamford Rd, Singapore 178887, Singapore" by specifying postal code as qualified field and limiting results by Singapore with parameter in=countryCode:SGP:

GET https://geocode.search.hereapi.com/v1/
    geocode
    ?qq=
        postalCode=178887
    &in=countryCode%3ASGP
    &apiKey={YOUR_API_KEY}

Alternatively, the country name or country code can be specified as the qualified country field:

GET https://geocode.search.hereapi.com/v1/
    geocode
    ?qq=
        postalCode=178887;
        country=Singapore
    &apiKey={YOUR_API_KEY}

Or country name or country code and postal code can be combined into a freeform query:

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

The response to either of the above queries is the complete address:

{
  "items": [
    {
      "title": "53 Stamford Rd, Singapore 178887, Singapore",
      "id": "here:af:streetsection:us5c0JNnSvmYKAY94exFYB:CgcIBCD7_IpyEAEaAjUz",
      "resultType": "houseNumber",
      "houseNumberType": "PA",
      "address": {
        "label": "53 Stamford Rd, Singapore 178887, Singapore",
        "countryCode": "SGP",
        "countryName": "Singapore",
        "county": "Singapore",
        "city": "Singapore",
        "district": "Central Business District",
        "street": "Stamford Rd",
        "postalCode": "178887",
        "houseNumber": "53"
      },
      "position": {
        "lat": 1.29427,
        "lng": 103.85078
      },
      "access": [
        {
          "lat": 1.29437,
          "lng": 103.85084
        }
      ],
      "mapView": {
        "west": 103.84988,
        "south": 1.29337,
        "east": 103.85168,
        "north": 1.29517
      },
      "scoring": {
        "queryScore": 1,
        "fieldScore": {
          "country": 1,
          "postalCode": 1
        }
      }
    }
  ]
}

Client applications still can combine address and postal code information into one query. The /geocode endpoint matches all the provided address components to find the result with higher confidence.

Additional information

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