Provide city and district information for postal codes

HERE Geocoding and Search/autocomplete and /geocode endpoints include an optional parameter, postalCodeMode, that enables getting detailed results when a postal code is linked to multiple districts or city areas. By default, the system returns only one result, which can leave the district or city name blank, or use a default name, potentially omitting the relevant details.

Description of the supported values:

cityLookup: When a postal code spans multiple cities, cityLookup returns all possible combinations of the postal code with the corresponding city names.
districtLookup: When a postal code spans multiple districts (within one city or across multiple cities), districtLookup returns all possible combinations of the postal code with the corresponding district and city names.

For example, the postal code "3977" in Australia covers multiple towns, such as Devon Meadows and Cannons Creek, as well as several suburbs (districts) of Melbourne, including Cranbourne, Skye, Botanic Ridge, and others.

In the example below, the user uses the /autocomplete endpoint to search for a postal code in Australia. Since the same postal code might appear in multiple countries, it is recommended to apply a country filter using in=countryCode:AUS parameter.

GET https://autocomplete.search.hereapi.com/v1/
    autocomplete
    ?q=3977
    &in=countryCode%3AAUS
    &limit=20
    &apiKey={YOUR_API_KEY}

The following parameters are used:

q - Enter a free-text query.
in - Search within a geographic area. Results will be returned if they are located within the specified area.
limit - Maximum number of results to be returned.
apiKey - Your API key.

In the default mode, HERE Geocoding and Search /autocomplete endpoint returns a single postal code result, with the district and city fields left empty:

{
  "items": [
    {
      "title": "Australia, VIC, 3977",
      "id": "here:cm:namedplace:25711684",
      "language": "en",
      "resultType": "locality",
      "localityType": "postalCode",
      "address": {
        "label": "3977, Victoria, Australia",
        "countryCode": "AUS",
        "countryName": "Australia",
        "stateCode": "VIC",
        "state": "Victoria",
        "postalCode": "3977"
      },
      "highlights": {
        "title": [
          { "start": 16,
            "end": 20 }],
        "address": {
          "label": [
            { "start": 0,
              "end": 4 }],
          "postalCode": [
            { "start": 0,
              "end": 4 }]
        }
      }
    }
  ]
}

The same query with the postalCodeMode=cityLookup parameter set:

GET https://autocomplete.search.hereapi.com/v1/
    autocomplete
    ?q=3977
    &in=countryCode%3AAUS
    &postalCodeMode=cityLookup
    &limit=20
    &apiKey={YOUR_API_KEY}

With the postalCodeMode=cityLookup parameter, HERE Geocoding and Search /autocomplete endpoint returns three postal code results — one for each city or town the postal code overlaps with — sorted by the population of each city:

{
  "items": [
    {
      "title": "Australia, VIC, 3977",
      "id": "here:cm:namedplace:25711684-1469261839",
      "language": "en",
      "resultType": "locality",
      "localityType": "postalCode",
      "address": {
        "label": "3977, Melbourne, Victoria, Australia",
        ...
        "city": "Melbourne",
        "postalCode": "3977"
      },
      ...
    },
    {
      "title": "Australia, VIC, 3977",
      "id": "here:cm:namedplace:25711684-1469258642",
      "language": "en",
      "resultType": "locality",
      "localityType": "postalCode",
      "address": {
        "label": "3977, Devon Meadows, Victoria, Australia",
        ...
        "city": "Devon Meadows",
        "postalCode": "3977"
      },
      ...
    },
    {
      "title": "Australia, VIC, 3977",
      "id": "here:cm:namedplace:25711684-1469259583",
      "language": "en",
      "resultType": "locality",
      "localityType": "postalCode",
      "address": {
        "label": "3977, Cannons Creek, Victoria, Australia",
        ...
        "city": "Cannons Creek",
        "postalCode": "3977"
      },
      ...
    }
  ]
}

With using the postalCodeMode parameter, it is even more important to apply a country filter, because multiple postal code results may exist in each country, and they will be sorted by the population of the city, not by country.

In Australia, suburb names are commonly used for addressing or destination selection. Therefore, the end-users may also want to see the suburb names associated with a postal code.

The same query with postalCodeMode=districtLookup parameter set:

GET https://autocomplete.search.hereapi.com/v1/
    autocomplete
    ?q=3977
    &in=countryCode%3AAUS
    &postalCodeMode=districtLookup
    &limit=20
    &apiKey={YOUR_API_KEY}

With postalCodeMode=districtLookup parameter, the /autocomplete endpoint returns more postal code results, because it considers not only the overlaps of the postal code with cities or towns, but also districts.

The city of Melbourne has multiple districts (suburbs), and nine of them share the postal code 3977. With postalCodeMode=cityLookup, the /autocomplete endpoint returns a single postal code result for 3977 in the city of Melbourne. However, with postalCodeMode=districtLookup, it returns nine results - one for each individual suburb.
The town of Cannons Creek has only one district, Cannons Creek. With postalCodeMode=districtLookup the /autocomplete endpoint continues to return a single result, but now includes the district name, Cannons Creek, in the result.
The town of Devon Meadows has a relatively low population, and as a result, HERE map content does not define a built-up area for it, so it isn’t coded as a district. With postalCodeMode=districtLookup, the /autocomplete endpoint continues to return the postal code with the city name Devon Meadows and an empty district field.

{
  "items": [
    {
      "title": "Australia, VIC, 3977, Cranbourne",
      ...
      "address": { ..., "city": "Melbourne", "district": "Cranbourne", ... },
      ...
    },
    {
      "title": "Australia, VIC, 3977, Cranbourne East",
      ...
      "address": { ..., "city": "Melbourne", "district": "Cranbourne East", ... },
      ...
    },
    {
      "title": "Australia, VIC, 3977, Cranbourne West",
      ...
      "address": { ..., "city": "Melbourne", "district": "Cranbourne West", ... },
      ...
    },
    {
      "title": "Australia, VIC, 3977, Cranbourne North",
      ...
      "address": { ..., "city": "Melbourne", "district": "Cranbourne North", ... },
      ...
    },
    {
      "title": "Australia, VIC, 3977, Cranbourne South",
      ...
      "address": { ..., "city": "Melbourne", "district": "Cranbourne South", ... },
      ...
    },
    {
      "title": "Australia, VIC, 3977, Skye",
      ...
      "address": { ..., "city": "Melbourne", district": "Skye", ... },
      ...
    },
    {
      "title": "Australia, VIC, 3977, Botanic Ridge",
      ...
      "address": { ..., "city": "Melbourne", "district": "Botanic Ridge", ... },
      ...
    },
    {
      "title": "Australia, VIC, 3977, Sandhurst",
      ...
      "address": { ..., "city": "Melbourne", "district": "Sandhurst", ... },
      ...
    },
    {
      "title": "Australia, VIC, 3977, Cannons Creek",
      ...
      "address": { ..., "city": "Cannons Creek", "district": "Cannons Creek", ... },
      ...
    },
    {
      "title": "Australia, VIC, 3977, Junction Village",
      ...
      "address": { ..., "city": "Melbourne", "district": "Junction Village", ... },
      ...
    },
    {
      "title": "Australia, VIC, 3977, Devon Meadows",
      ...
      "address": { ..., "city": "Devon Meadows", ...
      },
      ...
    }
  ]
}

When using postalCodeMode=districtLookup, one might expect that adding the city name to the query would limit the postal code results to that city. While this is generally true, the intent behind a query that combines a postal code with a city name is not always clear. In such cases, the user could be looking for a postal code within a large city, or they might be trying to distinguish between towns or villages with the same name. In the case of the /autocomplete endpoint, the user may even be searching for a street within the postal code, where the street name starts with the city name.

The HERE Geocoding and Search endpoints determine the intent on a case-by-case basis, selecting the result that is most precise.

For special postal code modes, where the desired result is a list of all cities or districts associated with a given postal code, it is recommended to use the types filter: types=postalCode.

The same query, with postalCodeMode=districtLookup, the city name "Melbourne" added, and the types=postalCode filter applied:

GET https://autocomplete.search.hereapi.com/v1/
    autocomplete
    ?q=3977+Melbourne
    &in=countryCode%3AAUS
    &postalCodeMode=districtLookup
    &types=postalCode
    &limit=20
    &apiKey={YOUR_API_KEY}

For this query, the /autocomplete endpoint returns nine postal code results - one for each suburb of the city Melbourne with which the postal code overlaps. Note that because the query includes the city name, the /autocomplete endpoint includes it in the result titles.

{
  "items": [
    {
      "title": "Australia, VIC, 3977, Melbourne, Cranbourne",
      ...
      "address": { ..., "city": "Melbourne", "district": "Cranbourne", ... },
      ...
    },
    {
      "title": "Australia, VIC, 3977, Melbourne, Cranbourne East",
      ...
      "address": { ..., "city": "Melbourne", "district": "Cranbourne East", ... },
      ...
    },
    {
      "title": "Australia, VIC, 3977, Melbourne, Cranbourne West",
      ...
      "address": { ..., "city": "Melbourne", "district": "Cranbourne West", ... },
      ...
    },
    {
      "title": "Australia, VIC, 3977, Melbourne, Cranbourne North",
      ...
      "address": { ..., "city": "Melbourne", "district": "Cranbourne North", ... },
      ...
    },
    {
      "title": "Australia, VIC, 3977, Melbourne, Cranbourne South",
      ...
      "address": { ..., "city": "Melbourne", "district": "Cranbourne South", ... },
      ...
    },
    {
      "title": "Australia, VIC, 3977, Melbourne, Skye",
      ...
      "address": { ..., "city": "Melbourne",  "district": "Skye", ... },
      ...
    },
    {
      "title": "Australia, VIC, 3977, Melbourne, Botanic Ridge",
      ...
      "address": { ..., "city": "Melbourne", "district": "Botanic Ridge", ... },
      ...
    },
    {
      "title": "Australia, VIC, 3977, Melbourne, Sandhurst",
      ...
      "address": { ..., "city": "Melbourne", "district": "Sandhurst", ... },
      ...
    },
    {
      "title": "Australia, VIC, 3977, Melbourne, Junction Village",
      ...
      "address": { ..., "city": "Melbourne", "district": "Junction Village", ...
      },
      ...
    }
  ]
}