Address lookup by postal code and house number

This tutorial demonstrates how to lookup an address using a house number and postal code.

Procedure

In countries with precise postal codes where the postal code does not describe an area but is only associated with a few addresses on the same street, it is possible to find an address by only providing the house number and postal code. In transport and parcel logistics, this is common.

The /geocode endpoint supports this use case with qualified and freeform queries.

This feature is available for Canada, the United Kingdom, the Netherlands, the United States of America (ZIP+4), Israel, Ireland, and Singapore. In Ireland and Singapore, where postal codes are precise up to the unique house number, the /geocode endpoint also supports address lookup by postal code.

For example, an address "425 W Randolph St, Chicago, IL 60606-1506, United States" can be also found by specifying only house number and postal code:

• houseNumber=425
• postalCode=60606-1506

The query can be formulated with the following:

GET https://geocode.search.hereapi.com/v1/
    geocode
    ?qq=
        houseNumber=425;
        postalCode=60606-1506
    &apiKey={YOUR_API_KEY}

Or as freeform query:

GET https://geocode.search.hereapi.com/v1/
    geocode
    ?q=425+60606-1506
    &apiKey={YOUR_API_KEY}

The following parameters are used:

• q - Enter a free-text query.
• 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.

The response to the above request has only two matched fields: house number and postal code, but the result type is the complete address:

{
  "items": [
    {
      "title": "425 W Randolph St, Chicago, IL 60606-1506, United States",
      "id": "here:af:streetsection:hdZ6xBRUraY46IQZCqZidD:CgcIBCDMlOElEAEaAzQyNShk",
      "resultType": "houseNumber",
      "houseNumberType": "PA",
      "address": {
        "label": "425 W Randolph St, Chicago, IL 60606-1506, United States",
        "countryCode": "USA",
        "countryName": "United States",
        "stateCode": "IL",
        "state": "Illinois",
        "county": "Cook",
        "city": "Chicago",
        "district": "West Loop",
        "street": "W Randolph St",
        "postalCode": "60606-1506",
        "houseNumber": "425"
      },
      "position": {
        "lat": 41.88432,
        "lng": -87.63877
      },
      "access": [
        {
          "lat": 41.88449,
          "lng": -87.63877
        }
      ],
      "mapView": {
        "west": -87.63998,
        "south": 41.88342,
        "east": -87.63756,
        "north": 41.88522
      },
      "scoring": {
        "queryScore": 1,
        "fieldScore": {
          "houseNumber": 1,
          "postalCode": 1
        }
      }
    }
  ]
}

Additional information

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