Address Fields
Loqate’s address structure is based on the OASIS Extensible Address Language (xAL) version 2.0, adapted to suit a flattened record structure. Some countries have more complex addressing structures than others. As such, the use of individual fields will vary based on the input country and the available reference data. The following fields are recognized, [in] designates a field that can be used on input, [out] designates a field that may be present on output, and [in,out] designates that a field can be used for both input and output. Please Note that the AdministrativeArea should be the full name or the postal authority accepted code. For example, ‘New York’ or ‘NY’ in the US, and “VALLE DEL CAUCA” in Colombia (there is no postal abbreviation). ISO-3166 administrative area codes (e.g. ‘CO-VAC’ for ‘VALLE DEL CAUCA’ in Colombia) are not recognized on input and should not be used but can be returned in our output via our enhanced ISO-3166 dataset Field descriptions for our geocode and certified products can be accessed from the main field descriptions menu.
Primary Address Fields
Primary fields (also known as atomic fields) are always populated and verified when appropriate.
| Address [in,out] | This field holds the full address, correctly formatted for mailing in the relevant country, including line breaks specified using the AddressLineSeparator option. |
| Address1, Address2, …, Address8 [in,out] |
These fields can be used to specify input address line data, and on output will contain the correctly formatted address split into individual address lines for mailing in the relevant country. Examples of recommended input are listed below:
Note: If the input values (Thoroughfare/premise) are entered on separate lines, the user may receive an unexpected outcome as this is not in a recommended input format.Example:
|
| ID [in,out] | Optional. This field will be passed through to the output unchanged. |
| DeliveryAddress [in,out] | This field holds the full address minus the Organization, Locality, AdministrativeArea hierarchy and PostalCode hierarchy fields, correctly formatted for mailing in the relevant country, including line breaks specified using the AddressLineSeparator option. |
| DeliveryAddress1, DeliveryAddress2, …, DeliveryAddress8 [in,out] | These fields contain the individual lines contained within the DeliveryAddress field. |
| Country [in] | This field is used to supply the country name or code (ISO 3166 2-character country code and ISO 3166 3-character country code). |
| CountryName [out] | This field holds the ISO 3166 official country name. |
| ISO3166-2 [out] | This field holds the ISO 3166 2-character country code. |
| ISO3166-3 [out] | This field holds the ISO 3166 3-character country code. |
| ISO3166-N [out] | This field holds the ISO 3166 3-digit numeric country code. |
| SuperAdministrativeArea [in,out] | This field holds the largest geographic data element within a country. |
| AdministrativeArea [in,out] | This field holds the most common geographic data element within a country. For instance, USA State, and Canadian Province. |
| SubAdministrativeArea [in,out] | This field holds the smallest geographic data element within a country. For instance, USA County. |
| Locality [in,out] | This field holds the most common population center data element within a country. For instance, USA City, Canadian Municipality. |
| DependentLocality [in,out] | This field holds a smaller population center data element, dependent on the contents of the Locality field. For instance, Turkish Neighborhood. |
| DoubleDependentLocality [in,out] | This field holds the smallest population center data element, dependent on both the contents of the Locality and DependentLocality fields. For instance, UK Village. |
| Thoroughfare [in,out] | This field holds the most common street or block data element within a country. For instance, USA Street. |
| DependentThoroughfare [in,out] | This field holds the dependent street or block data element within a country. For instance, UK Dependent Street. |
| Building [in,out] | This field contains the descriptive name identifying an individual location, should one exist. |
| Premise [in,out] | This field contains the alphanumeric code identifying an individual location, should one exist. |
| SubBuilding [in,out] | This field contains the secondary identifiers for a particular delivery point. For instance, “FLAT 1” or “SUITE 212”. |
| SubBuildingFloor [in,out] | This field contains the parsed floor information within the SubBuilding field, and includes the floor label (or type) and a numeric where applicable. For example, “L7” or “Fl 12”. |
| PostalCode [in,out] | This field contains the complete postal code for a particular delivery point, should such detail be able to be determined. |
| PostalCodePrimary [out] | This field contains the primary postal code used for a particular country. For instance, USA Zip, Canadian Postcode, Indian PINcode. |
| PostalCodeSecondary [out] | This field contains secondary postal code information, if used in a particular country and if such detail is able to be determined and reference data is available. For instance, USA Zip Plus 4. |
| Organization [in,out] | This field contains the business name associated with a particular delivery point, should one exist. |
| PostBox [in,out] | This field contains the post box for a particular delivery point, should one exist. |
| AddressFormat [out] | If Server Option “OutputAddressFormat“ is “Yes“, then this field will contain the fields used to construct the “Address“ Field. For example, “Organization<BR>DeliveryAddress<BR>Locality AdministrativeArea PostalCode“. The default “<BR>“ line breaks can be changed with the AddressLineSeparator Server Option. |
| DeliveryAddressFormat [out] | If Server Option “OutputAddressFormat“ is “Yes“, then this field will contain the fields used to construct the “DeliveryAddress“ Field. For example, “Organization<BR>DeliveryAddress<BR>Locality AdministrativeArea PostalCode“. The default “<BR>“ line breaks can be changed with the AddressLineSeparator Server Option. |
| AVC (Address Verification Code) [out] | A response code which includes information associated with the parsing and matching of the address record. Use this to identify the level to which an address has been verified. See the AVC page for more information. |
| AQI (Address Quality Index) [out] | Offers a view of overall address quality (see the AQI page for more information), but is not used as a metric for deciding whether to accept an address which has been processed via Verify. Please use the AVC to verify addresses. |
| Sequence [out] | When multiple addresses are included in a single Verify request this counter will show the order of the addresses from the input. For example: 7 represents the 7th address in the input request. |
Sub-Fields
Sub-fields are populated when the level of parsing detail exists for the particular country. Sub-fields are only verified when they are supported by the reference data for the particular country. Therefore they are not guaranteed to be populated or verified in the output. For example, a Sub-field may be populated from the parsed input, but may not be able to be verified. Please check the associated Field Status to confirm.
| Unmatched [out] | This field can hold any information in the input address fields that is unable to be parsed to a particular address field. Read more about the Unmatched field here. |
| MatchRuleLabel [out] |
Loqate Engine uses a set of rules to match the input with the reference data. Each rule is identified by a match rule label. Please refer to the below links for more information regarding the Match Rules. |
| HyphenClass [out] | https://support.loqate.com/documentation/fielddescrip/objfeilds/ |
| Contact [in,out] | This field can hold contact name information. |
| Function [in,out] | This field can hold function or job title information. |
| Department [in,out] | This field can hold organizational department information. |
| AdministrativeAreaName [out] | This field holds the name indicator within the AdministrativeArea field, should one exist. For example, Taipai where the AdministrativeArea is Taipai City. |
| AdministrativeAreaTrailingType [out] | This field holds the trailing AdministrativeArea type, should one exist. For example, City where the AdministrativeArea is Taipai City. |
| AdministrativeAreaType [out] | This field holds the AdministrativeArea type, should one exist. For example, City where the AdministrativeArea is Taipai City. |
| LocalityExtra [out] | This field is used to hold information that could be present along with the Locality. This information is not considered as part of the Postal authority data but is still necessary for parsing the address in order to obtain a complete delivery address. Available if a sufficient level of parsing detail exists within a particular country. Example: 12 rue de la Gare, 75019 PARIS CEDEX, France. CEDEX will be considered as Locality Extra. |
| LocalitySpecial |
The LocalitySpecial field combines both the Locality and LocalityExtra components, to capture specific locality information that includes essential details for accurate address parsing and delivery. For example, in the address “12 rue de la Gare, 75019 PARIS CEDEX, France,” the term “Paris CEDEX” represents the LocalitySpecial. It encompasses both the primary locality (Paris) and the additional locality information (CEDEX) that is necessary for a complete and precise delivery address. |
| LocalityName [out] | This field holds the name indicator within the Locality field, should one exist. For example: Jeju where the Locality is Jeju-Si. |
| LocalityType [out] | This field holds the type indicator for Locality, should one exist. For example: Dist. where the Locality is Da’an Dist. |
| LocalityTrailingType [out] | This field holds the type indicator for Locality, should one exist. For example: Dist. where the Locality is Da’an Dist. |
| DependentLocalityName [out] | This field holds the name indicator within the DependentLocality field, should one exist. For instance, if DependentLocality contains “Dong Cheng Qu” DependentLocalityName contains “Dong Cheng” if a sufficient level of parsing detail exists for the particular country. |
| DependentLocalityType [out] | This field is used to hold the DependentLocality indicator within the DependentLocality field, should one exist. For instance, if DependentLocality contains “Dong Cheng Qu” DependentLocalityType contains “Qu” if a sufficient level of parsing detail exists for the particular country. |
| DependentLocalityLeadingType [out] | This field holds the leading dependent locality type indicator, should one exist. For example, “Rancheria San Jose Cacahuatepec” where the DependentLocality is Ciudad Renacimiento. |
| DoubleDependentLocalityName [out] | This field holds the name indicator within the DoubleDependentLocality field, should one exist. For instance, if DoubleDependentLocality contains “Xin Zhuang Zhen” DoubleDependentLocalityName contains “Xin Zhuang” if a sufficient level of parsing detail exists for the particular country. |
| DoubleDependentLocalityType [out] | This field is used to hold the DoubleDependentLocality indicator within the DoubleDependentLocality field, should one exist. For instance, if DoubleDependentLocality contains “Xin Zhuang Zhen” DoubleDependentLocalityType contains “Zhen” if a sufficient level of parsing detail exists for the particular country. |
| ThoroughfarePreDirection [out] | This field holds the prefix directional contained within the Thoroughfare field, should one exist. For instance, if Thoroughfare contains “N MAIN ST” ThoroughfarePreDirection contains “N” if a sufficient level of parsing detail exists for the particular country. |
| ThoroughfareType [out] | This field holds the type of thoroughfare should one exist. Examples include Road, Vei, St, Rua, Avenita, Pereulok, 路 |
| ThoroughfareLeadingType [out] | This field holds the leading thoroughfare type indicator within the Thoroughfare field, should one exist. For instance, if Thoroughfare contains “RUE DE LA GARE” ThoroughfareLeadingType contains “RUE” if a sufficient level of parsing detail exists for the particular country. |
| ThoroughfareName [out] | This field holds the name indicator within the Thoroughfare field, should one exist. For instance, if Thoroughfare contains “N MAIN ST” ThoroughfareName contains “MAIN” if a sufficient level of parsing detail exists for the particular country. |
| ThoroughfareTrailingType [out] | This field holds the trailing thoroughfare type indicator within the Thoroughfare field, should one exist. For instance, if Thoroughfare contains “N MAIN ST” ThoroughfareTrailingType contains “ST” if a sufficient level of parsing detail exists for the particular country. |
| ThoroughfarePostDirection [out] | This field holds the postfix directional contained within the Thoroughfare field, should one exist. For instance, if Thoroughfare contains “MAIN ST N” ThoroughfarePostDirection contains “N” if a sufficient level of parsing detail exists for the particular country. |
| DependentThoroughfarePreDirection [out] | This field holds the prefix directional contained within the DependentThoroughfare field, should one exist. For instance, if DependentThoroughfare contains “N MAIN ST” DependentThoroughfarePreDirection contains “N” if a sufficient level of parsing detail exists for the particular country. |
| DependentThoroughfareLeadingType [out] | This field holds the leading thoroughfare type indicator within the DependentThoroughfare field, should one exist. For instance, if DependentThoroughfare contains “RUE DE LA GARE” DependentThoroughfareLeadingType contains “RUE” if a sufficient level of parsing detail exists for the particular country. |
| DependentThoroughfareName [out] | This field holds the name indicator within the DependentThoroughfare field, should one exist. For instance, if DependentThoroughfare contains “N MAIN ST” DependentThoroughfareName contains “MAIN” if a sufficient level of parsing detail exists for the particular country. |
| DependentThoroughfareTrailingType [out] | This field holds the trailing thoroughfare type indicator within the DependentThoroughfare field, should one exist. For instance, if DependentThoroughfare contains “N MAIN ST” DependentThoroughfareTrailingType contains “ST” if a sufficient level of parsing detail exists for the particular country. |
| DependentThoroughfarePostDirection [out] | This field holds the postfix directional contained within the DependentThoroughfare field, should one exist. For instance, if DependentThoroughfare contains “MAIN ST N” DependentThoroughfarePostDirection contains “N” if a sufficient level of parsing detail exists for the particular country. |
| BuildingLeadingType [out] | This field holds the leading building type indicator within the Building field, should one exist. For instance, if Building contains “BLOC C” BuildingLeadingType contains “BLOC” if a sufficient level of parsing detail exists for the particular country. |
| BuildingName [out] | This field holds the name indicator within the Building field, should one exist. For instance, if Building contains “WESTMINSTER HOUSE” BuildingName contains “WESTMINSTER” if a sufficient level of parsing detail exists for the particular country. |
| BuildingType [out] | This field is used to hold the Building indicator within the Building field, should one exist. Examples include Place, 城. |
| BuildingTrailingType [out] | This field holds the trailing building type indicator within the Building field, should one exist. For instance, if Building contains “WESTMINSTER HOUSE” BuildingTrailingType contains “HOUSE” if a sufficient level of parsing detail exists within a particular country. |
| PremiseType [out] | This field contains the leading premise type indicator within the Premise field, should one exist. For instance, if Premise contains “Plot 7/7A” PremiseType contains “Plot” if a sufficient level of parsing detail exists within a particular country. |
| PremiseNumber [out] | This field contains the alphanumeric indicator within the Premise field, should one exist. For instance, if Premise contains “Plot 7/7A” PremiseNumber contains “7/7A” if a sufficient level of parsing detail exists within a particular country. |
| PremiseExtra [out] | This field is used to hold information that could be present as part of the Premise field. This information is not considered as part of the Postal authority data but is still necessary for parsing the address in order to obtain a complete delivery address. Available if a sufficient level of parsing detail exists within a particular country. Example: In French address, the Premise number could be followed by words bis and ter which will be considered as Premise Extra . 25 bis rue Emile Zola, 91190 GIF SUR YVETTE, France. Bis will be considered as PremiseExtra. |
| SubBuildingType [out] | This field contains the leading sub-building type indicator within the SubBuilding field, should one exist. For instance, if SubBuilding contains “FLAT 1” SubBuildingType contains “FLAT” if a sufficient level of parsing detail exists within a particular country. |
| SubBuildingLeadingType [out] | This field contains the sub-building type indicator within the SubBuilding field, should one exist. For instance, if SubBuilding contains “FLAT 1” SubBuildingLeadingType contains “FLAT” if a sufficient level of parsing detail exists within a particular country. |
| SubBuildingNumber [out] | This field contains the alphanumeric indicator within the SubBuilding field, should one exist. For instance, if SubBuilding contains “FLAT 1” SubBuildingNumber contains “1” if a sufficient level of parsing detail exists within a particular country. |
| SubBuildingName [out] | This field contains the descriptive name within the SubBuilding field. For instance, if SubBuilding contains “BASEMENT FLAT” SubBuildingName contains “BASEMENT FLAT”. |
| SubBuildingBlock [out] | This field contains the secondary identifiers for a particular delivery point. For instance – BLOQUE 7. |
| SubBuildingDoor [out] | This field contains the secondary identifiers for a particular delivery point. For instance PUERTA D. |
| SubBuildingStaircase [out] | This field contains the secondary identifiers for a particular delivery point. For instance PUERTA D. |
| Bolignummer (Norway only) [out] | The utility unit number consist of a letter followed by four numbers (Norway/NO/NOR only). Examples include: H0001, L0002, U0004, K0032. |
| DeliveryInstallationAreaName (Canada only) [out] | The name of a village, town, municipality, city, or metropolitan area that forms part of a Delivery Installation Name (Canada/CA/CAN only). Examples include: Ladysmith, Roxton Pond. |
| DeliveryInstallationType (Canada only) [out] | An abbreviation that represents the type of installation (Canada/CA/CAN only). Examples include: STN – Postal Station, PO – Post Office, BDP – Bureau De Poste. |
| DeliveryInstallationQualifierName (Canada only) [out] | When more than one delivery installation serves an area described by the Delivery Installation Area Name, the qualifier name uniquely identifies the delivery installation (Canada/CA/CAN only). Examples include: Cap-A-L’aigle, B, St Michel, 32, Bank Hunt Club. |
| RouteType (Canada only) [out] | A code that identifies the type of route service (Canada/CA/CAN only). Examples include: RR – Rural Route, SS – Suburban Service. |
| RouteNumber Canada only) [out] | A number that identifies the specific Delivery Mode (Canada/CA/CAN only). Examples include: 22, 62, 404. |
| BranchName (Canada only) [out] | Branch name of Department field (Canada/CA/CAN only). Examples include: Agence De Parcs Canada, Fisheries and Oceans, Ottawa District Office. |
| MakaniNumber (United Arab Emirates only) [out] | A Makani number is a 10-digit number which gives you the exact location of the entrance of a building (United Arab Emirates/AE/ARE only). For example: 3000595279. |
| ShortAddressCode (Saudi Arabia only) [out] | A short address that consists of four letters followed by four numbers (Saudi Arabia/SA/SAU only). For example: RGSA3808. |
| OrganizationName [out] | This field contains the name indicator within the Organization field, should one exist. For instance, if Organization contains ‘Loqate Inc” OrganizationName contains “Loqate” if a sufficient level of parsing detail exists for the particular country. |
| OrganizationType [out] | This field contains the type indicator contained within the Organization field, should one exist. For instance, if Organization contains “Loqate Inc” OrganizationType contains “Inc” if a sufficient level of parsing detail exists for the particular country. |
| OrganizationTrailingType [out] | This field contains the trailing type indicator contained within the Organization field, should one exist. For example: Corp., Gmbh. |
| PostBoxType [out] | This field contains the type indicator contained within the PostBox field, should one exist. For instance, if PostBox contains “PO BOX 1234” PostBoxType contains “PO BOX” if a sufficient level of parsing detail exists for the particular country. |
| PostBoxNumber [out] | This field contains the alphanumeric indicator within the PostBox field, should one exist. For instance, if PostBox contains “PO BOX 1234” PostBoxNumber contains “1234” if a sufficient level of parsing detail exists for the particular country. |
| BoxBagLobbyName (New Zealand only) [out] | Box lobby name or New Zealand Post shop name (New Zealand/NZ/NZL only). Examples include: MAUNGATAPERE POSTCENTRE, NEWMARKET POSTSHOP, MOUNT COOK. |