> For the complete documentation index, see [llms.txt](https://docs.mastersoftgroup.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mastersoftgroup.com/loqate-harmony-api/guides/best-practices/address-field-mappings.md).

# Address Field Mappings

### Universal Response Objects / Persistent Data Hierarchy <a href="#universal" id="universal"></a>

We have three different types of objects suited to primary business regions being Australia, New Zealand and International (rest of world).&#x20;

We've created universal response components to enable consistent information no matter which address object best suits your business need.

When integrating to a platform we recommend using the universal response objects for mapping for consistency and scale across regions.

### Recommended field mappings

This fields remain constant across AU, NZ and INTL address response packages. We recommend using this mapping to reduce integration effort.&#x20;

We have very detailed response allowing you to full customise how you want to compile any address component.&#x20;

<table><thead><tr><th width="288">Generic Field</th><th width="243">Recommended mapping</th><th>Description</th></tr></thead><tbody><tr><td>Building names</td><td>buildingName</td><td>Building Name component of the address (e.g. 'ANZAC HOUSE').</td></tr><tr><td>Subdwelling (long)</td><td>subdwelling</td><td>Compiled subdwelling components of the address 'UNIT 2'. This includes subdwelling, floor, block and lot information.</td></tr><tr><td>Street number</td><td>streetNumber</td><td>Street Number component of the address '45A'</td></tr><tr><td>Street name</td><td>street</td><td>Compiled Street Name and Street Type. 'HIGH STREET'</td></tr><tr><td>City/Locality/Suburb</td><td>attributes.City</td><td>A smaller region contained in a Province. Australia known as Locality, in NZ is Suburb, around the world it can be City.</td></tr><tr><td>Zip/Postcode</td><td>postcode</td><td>Postcode or ZIP code of address</td></tr><tr><td>Region/State/Province (Short)</td><td>attributes.ProvinceCode</td><td>This is the highest region contained within a country. 'VIC'</td></tr><tr><td>Region/State/Province (Long)</td><td>attributes.ProvinceName</td><td>This is the highest region contained within a country. 'Victoria'</td></tr><tr><td>Country2 (Short)</td><td>attributes.CountryIso2</td><td>Country in ISO2 format. 'AU'</td></tr><tr><td>Country3 (Short)</td><td>attributes.CountryIso3</td><td>Country in ISO3 format. 'AUS'</td></tr><tr><td>Country (Long)</td><td>country</td><td>Country in full text. 'Australia'</td></tr><tr><td>Latitude</td><td>attributes.Latitude</td><td>Geocode of latitude "-34.77910653"</td></tr><tr><td>Longitude</td><td>attributes.Longitude</td><td>Geocode of longitude "139.55428910"</td></tr></tbody></table>

### Components for labels or integration

Every supplier has a preferred configuration. We give you the tools to compile as you need to fit your use case.&#x20;

#### **Example 1: Australia Post Standard Address**

AUPAF barcode: {attributes.Barcode}

Address Line 1: {buildingName} {subdwelling}  {userInferred}&#x20;

Address Line 2: {streetNumber} {street} {streetSuffix} {postal}

Address Line 3: {attributes.City} {attributes.ProvinceCode} {postcode} {attributes.CountryIso3}&#x20;

#### **Example 2: New Zealand Standard Address**

NZPAF barcode: {attributes.DPID}

Address Line 1: {buildingName} {subdwelling}  {userInferred}&#x20;

Address Line 2: {streetNumber} {street} {streetSuffix} {postal} ,{suburb}

Address Line 3: {attributes.City} {attributes.ProvinceCode} {postcode} {attributes.CountryIso3}&#x20;

#### **Example 3: American Standard (INTL)**

Address Line 1: {streetNumber} {street} {streetSuffix} {district} {postal}&#x20;

Address Line 2: {buildingName}  {subdwelling}  {userInferred}&#x20;

Address Line 3: {attributes.City} {attributes.ProvinceCode} {postcode} {attributes.CountryIso2}&#x20;

#### Example 4: Two lines with regions American

Address Line 1: {streetNumber} {street} {streetSuffix} {postal} ,{suburb/district}

Address Line 2: {buildingName} {subdwelling} {userInferred}&#x20;

City: {attributes.City}&#x20;

Zip: {postcode}

Province code: {attributes.ProvinceCode}&#x20;

Country code: {attributes.CountryIso2}&#x20;


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.mastersoftgroup.com/loqate-harmony-api/guides/best-practices/address-field-mappings.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.