Handle secondary unit information

Accurate address input is critical for delivery and logistics workflows, as it directly impacts successful drop-offs and route efficiency. Drivers often rely on inputs entered by end-users, which often include addresses with secondary unit details such as apartment numbers, suites, or units.

This tutorial demonstrates how you can use the /autocomplete endpoint to support completion of addresses with secondary units.

The /autocomplete endpoint supports secondary unit (sub-premise) information, such as apartment numbers, suites, or units, using Sub-Premise Information and Micro Point Address (MPA) support.

The following section shows how the /autocomplete endpoint handles three common scenarios:

A delivery address includes sub-premise information that cannot be resolved.

When a user enters a query that includes apartment or unit information (for example, an apartment number or suite), the /autocomplete endpoint attempts to interpret and use this information during matching. If the sub-premise information cannot be matched, the reason could be:

• The customer application does not have access to use MPA features or doesn't set the parameter in the request.
• The MPA information is not in the data.
• MPA feature is not supported in this country.

In these situations, the /autocomplete endpoint detects and parses the unit-related tokens in the query but does not require them to match. Instead, the service continues matching using only the house number and street-level information.

This behavior ensures that sub-premise information does not prevent suggestions from being returned. Even when the unit information cannot be resolved, the /autocomplete endpoint still provides relevant suggestions at the house number level.

This is important because /autocomplete typically expects all query tokens to match. Allowing unmatched unit information helps maintain suggestion quality and prevents reduced success rates. It is especially useful in regions where users commonly begin queries with apartment or unit details.

Result: The /autocomplete returns relevant house number suggestions, even when the unit information in the query cannot be resolved.

Request example:

GET /v1/autocomplete?q=unit 5/123 Geo&in=countryCode:AUS

Response example:

{
   title: "Australia, NSW, 2000, The Rocks, 123 George St",
   id: here:af:streetsection:YQEnxljdtksncO8QD.lx2D:CggIBCDVxpjRAhABGgMxMjM,
   language: "en",
   resultType: "houseNumber",
   houseNumberType: "PA",
   address: {
      label: "123 George St, The Rocks NSW 2000, Australia",
      countryCode: "AUS",
      countryName: "Australia",
      stateCode: "NSW",
      state: "New South Wales",
      city: "Sydney",
      district: "The Rocks",
      street: "George St",
      postalCode: "2000",
      houseNumber: "123"
   },

In this case, the delivery is still associated with the correct building, even though the sub-premise information could not be resolved.

A delivery address includes an apartment or unit details that match a Micro Point Address

When a user enters a query that includes apartment or unit information (for example, an apartment number or suite), the /autocomplete endpoint can use this information when Micro Point Address (MPA) support is enabled. The customer application must be authorized to use MPA and set the parameter with=MPA.

In this case, /autocomplete detects and parses the unit-related parts of the query and attempts to match them against MPA data associated with the corresponding house number.

If a match is found, /autocomplete returns a suggestion at the micro point (unit) level, providing a more precise address.

If no match is found, the service falls back to standard behavior. The sub-premise information is ignored, and the response includes a house number–level suggestion. This fallback ensures consistent results and avoids blocking suggestions when unit-level data is unavailable.

Result: /autocomplete returns a Micro Point Address suggestion when a match is found. Otherwise, it returns standard house number suggestions, as described in the first scenario.

Request example of matching to an MPA:

GET /v1/autocomplete?q=101/2 Gentian Dr Aru&in=countryCode:AUS&with=MPA

Response example:

{
   title: "Australia, QLD, 4214, Arundel, 101/2 Gentian Dr",
   id: here:af:streetsection:jZUaMY6NNdXKbdHRhGC33C:ChYIBCDipMbWAjIMCggIFCDgi5ygAxAEEAEaATI,
   language: "en",
   resultType: "houseNumber",
   houseNumberType: "MPA",
   address: {
      label: "101/2 Gentian Dr, Arundel QLD 4214, Australia",
      countryCode: "AUS",
      countryName: "Australia",
      stateCode: "QLD",
      state: "Queensland",
      city: "Gold Coast",
      district: "Arundel",
      street: "Gentian Dr",
      postalCode: "4214",
      houseNumber: "2",
      unit: "101"
   }

The result represents a resolved MPA suitable for unit-level delivery.

Discovering available Micro Point Addresses from a building

In some applications, users are not expected to enter sub-premise information, but the application still wants to:

• Indicate that additional unit-level addresses exist for a given address.
• Allow the user to discover them after selecting a suggestion.

For this use case, /autocomplete provides the parameter: show=hasRelatedMPA

For each point address suggestion, /autocomplete returns a flag indicating:

• Whether MPAs are available for that location
• /autocomplete does not return the MPA themselves, to avoid:
  • Excessive result counts
  • Reduced performance in suggestion lists

To fetch the actual micropoint addresses:

• Use the /lookup endpoint
• With the parameter: showRelated=MPA (Note: This parameter is restricted and requires authorization)

Result:

• /autocomplete indicates availability of MPA data
• /lookup retrieves the full list of sub-premise addresses

Request example:

GET /v1/autocomplete?q=95-99 Tram R&show=hasRelatedMPA

Response example:

{
  "title": "95-99 Tram Rd, Doncaster VIC 3108, Australia",
  "id": "here:af:streetsection:ZV8woXvI1T787UC1-.w-VB:CggIBCCMg-GgARABGgU5NS05OQ",
  "resultType": "houseNumber",
  ......
  "hasRelatedMPA": true
}

When hasRelatedMPA is true, the returned id can be used with/lookup to retrieve all related MPA and finalize the address.

Lookup id request example:

GET /v1/lookup?id=here:af:streetsection:ZV8woXvI1T787UC1-.w-VB:CggIBCCMg-GgARABGgU5NS05OQ&showRelated=MPA

Response example:

{
   related: [
      {
         relationship: "MPA",
         title: "1/95-99 Tram Rd, Doncaster VIC 3108, Australia",
         id: here:af:streetsection:ZV8woXvI1T787UC1-.w-VB:ChYIBCCMg-GgATIMCggIFCCmprigAxAEEAEaBTk1LTk5,
         resultType: "houseNumber",
         houseNumberType: "MPA",
         address: {
            label: "1/95-99 Tram Rd, Doncaster VIC 3108, Australia",
            unit: "1"
         },
         position: {
            lat: -37.78871,
            lng: 145.12478
         }
      },
      {
         relationship: "MPA",
         title: "10/95-99 Tram Rd, Doncaster VIC 3108, Australia",
         id: here:af:streetsection:ZV8woXvI1T787UC1-.w-VB:ChYIBCCMg-GgATIMCggIFCC15b-gAxAEEAEaBTk1LTk5,
         resultType: "houseNumber",
         houseNumberType: "MPA",
         address: {
            label: "10/95-99 Tram Rd, Doncaster VIC 3108, Australia",
            unit: "10"
         },
         position: {
            lat: -37.78871,
            lng: 145.12478
         }
      },
      ......
	]
}

Availability and Restrictions