Skip to main content

Postal Addresses

Postal addresses vary widely in different regions of the world. In order to write global code, it's convenient to standardize a schema that is able to capture all different variants. This allows for example to more easily store addresses across all regions into the same DB table. Unfortunately there is not a generally accepted standard and different solutions have been adopted over time. HTML 5.1 breaks down addresses into 7 fields named address-line1 through address-line3 and address-level4 through address-level1. This generic mapping sounds easy but in order to build a UI, it requires metadata to map logical components to elements that users in each region will recognize. It also needs validation rules that will vary by region and require additional metadata. One of the most complete publicly-available repositories of metadata about postal addresses is made available by Google as part of the libaddressinput widget.

The schema terminology is different but it can be mapped to the HTML one:

  • N → Name → name
  • O → Organization → organization
  • A → Address Lines → address-line1 through address-line3
  • D → Sublocality → address-level3
  • C → Locality → address-level2
  • S → Administrative Area → address-level1
  • Z → Postal Code → postal-code
  • X → Sorting Code → address-level4
  • Country (implicit) → country

Address Levels​

The meaning of each part varies by region as follows:

  • Sublocality

    • "neighborhood": Brazil, Iran, Mexico
    • "district": China, South Korea
    • "townland": Ireland
    • "village_township": Malaysia
    • "suburb": DEFAULT

  • Locality

    • "district": Hong Kong SAR China, Peru, Sudan, Syria, Turkey
    • "post_town": Norway, Svalbard & Jan Mayen, Sweden, United Kingdom
    • "suburb": Australia
    • "city": DEFAULT

  • Administrative Area

    • "state": American Samoa, Australia, Brazil, India, Malaysia, Marshall Islands, Mexico, Micronesia, Nigeria, Northern Mariana Islands, Palau, U.S. Outlying Islands, U.S. Virgin Islands, United States, Venezuela
    • "island": Bahamas, Cape Verde, Cayman Islands, French Polynesia, Kiribati, Seychelles, St. Kitts & Nevis, Tuvalu
    • "department": Colombia, Honduras, Nicaragua
    • "parish": Barbados, Jamaica
    • "county": Ireland, Taiwan
    • "oblast": Russia, Ukraine
    • "emirate": United Arab Emirates
    • "area": Hong Kong SAR China
    • "prefecture": Japan
    • "do_si": South Korea
    • "district": Nauru
    • "province": DEFAULT

  • Postal Code

    • "zip": American Samoa, Guam, Marshall Islands, Micronesia, Northern Mariana Islands, Palau, Puerto Rico, U.S. Outlying Islands, U.S. Virgin Islands, United States
    • "eircode": Ireland
    • "pin": India
    • "postal": DEFAULT

Used Fields​

Not all fields are used by all regions, but there are similarities. The following table shows the range of variations of used fields across regions.

FieldsRegions
address-line, city, postalAfghanistan, Albania, Algeria, Andorra, Anguilla, Ascension Island, Austria, Azerbaijan, Bahrain, Bangladesh, Belgium, Bermuda, Bhutan, Bosnia & Herzegovina, British Indian Ocean Territory, British Virgin Islands, Brunei, Bulgaria, Cambodia, Croatia, Cyprus, Czechia, Denmark, Dominican Republic, Ecuador, Estonia, Eswatini, Ethiopia, Falkland Islands, Faroe Islands, Finland, France, Georgia, Germany, Greece, Greenland, Guatemala, Guernsey, Guinea, Guinea-Bissau, Haiti, Hungary, Iceland, Isle of Man, Israel, Jersey, Jordan, Kenya, Kosovo, Kuwait, Kyrgyzstan, Laos, Latvia, Lebanon, Lesotho, Liberia, Liechtenstein, Lithuania, Luxembourg, Madagascar, Maldives, Malta, Mauritius, Moldova, Montenegro, Morocco, Myanmar (Burma), Namibia, Nepal, Netherlands, Niger, North Macedonia, Oman, Pakistan, Paraguay, Pitcairn Islands, Poland, Portugal, Romania, San Marino, Saudi Arabia, Senegal, Serbia, Slovakia, Slovenia, South Georgia & South Sandwich Islands, Sri Lanka, St. Helena, St. Vincent & Grenadines, Switzerland, Tajikistan, Tanzania, Tristan da Cunha, Tunisia, Turkmenistan, Turks & Caicos Islands, Vatican City, Western Sahara, Zambia, Åland Islands
address-line, cityAngola, Antarctica, Antigua & Barbuda, Aruba, Belize, Benin, Bolivia, Botswana, Bouvet Island, Burundi, Cameroon, Caribbean Netherlands, Central African Republic, Chad, Comoros, Congo - Brazzaville, Congo - Kinshasa, Cook Islands, Curaçao, Djibouti, Dominica, Equatorial Guinea, Eritrea, Fiji, French Southern Territories, Gabon, Gambia, Ghana, Grenada, Guyana, Libya, Mali, Mauritania, Montserrat, Niue, Palestinian Territories, Qatar, Rwanda, Samoa, Sierra Leone, Sint Maarten, Solomon Islands, South Sudan, St. Lucia, São Tomé & Príncipe, Timor-Leste, Togo, Tokelau, Tonga, Trinidad & Tobago, Uganda, Vanuatu, Yemen, Zimbabwe
address-line, city, postal, provinceArgentina, Armenia, Belarus, Canada, Chile, Christmas Island, Cocos (Keeling) Islands, Costa Rica, Cuba, Egypt, El Salvador, Heard & McDonald Islands, Indonesia, Iraq, Italy, Kazakhstan, Mongolia, Mozambique, Norfolk Island, North Korea, Papua New Guinea, Somalia, Spain, Uruguay, Uzbekistan, Vietnam
address-line, city, postal, sorting-codeFrench Guiana, Guadeloupe, Martinique, Mayotte, Monaco, New Caledonia, Réunion, St. Barthélemy, St. Martin, St. Pierre & Miquelon, Wallis & Futuna
address-line, city, state, zipAmerican Samoa, Marshall Islands, Micronesia, Northern Mariana Islands, Palau, U.S. Outlying Islands, U.S. Virgin Islands, United States
address-line, city, islandBahamas, Kiribati, Seychelles, St. Kitts & Nevis, Tuvalu
address-line, post_town, postalNorway, Svalbard & Jan Mayen, Sweden, United Kingdom
address-line, city, department, postalColombia, Honduras, Nicaragua
address-line, city, sorting-codeBurkina Faso, Malawi
address-line, city, neighborhood, postal, stateBrazil, Mexico
address-line, city, island, postalCape Verde, French Polynesia
address-line, postalGibraltar, Singapore
address-line, city, zipGuam, Puerto Rico
address-line, districtNauru, Syria
address-line, city, postal, suburbNew Zealand, South Africa
address-line, city, provincePanama, Suriname
address-line, district, postal, provincePeru, Turkey
address-line, city, postal, province, suburbPhilippines, Thailand
address-line, city, oblast, postalRussia, Ukraine
address-line, emirateUnited Arab Emirates
address-line, postal, state, suburbAustralia
address-line, city, parish, postalBarbados
address-line, city, sorting-code, sorting-codeCôte d’Ivoire
address-line, city, district, postal, provinceChina
address-line, area, districtHong Kong SAR China
address-line, city, county, eircode, townlandIreland
address-line, city, pin, stateIndia
address-line, city, neighborhood, postal, provinceIran
address-line, city, parish, sorting-codeJamaica
address-line, postal, prefectureJapan
address-line, city, district, do_si, postalSouth Korea
address-line, island, postalCayman Islands
address-lineMacao SAR China
address-line, city, postal, state, village_townshipMalaysia
address-line, city, postal, state, suburbNigeria
address-line, district, postalSudan
address-line, city, county, postalTaiwan
address-line, city, postal, stateVenezuela

Administrative Areas​

In some regions, administrative areas are enumerable so UI elements like dropdowns are often used.

  • Andorra keys: names:
  • Argentina keys:
  • Armenia keys: lnames:
  • Australia keys: names:
  • Bahamas keys: names:
  • Brazil keys: names:
  • Canada keys: names:
  • Cape Verde keys:
  • Cayman Islands keys:
  • Chile keys: names:
  • China keys: names: lnames:
  • Cuba keys:
  • Egypt keys: lnames:
  • El Salvador keys: names:
  • Hong Kong SAR China keys: names:
  • India keys: names:
  • Indonesia keys: lnames:
  • Iran keys: lnames:
  • Ireland keys:
  • Italy keys: names:
  • Jamaica keys:
  • Japan keys: lnames:
  • Malaysia keys:
  • Mexico keys: names:
  • Mozambique keys:
  • Nauru keys:
  • Nicaragua keys:
  • Nigeria keys:
  • North Korea keys: lnames:
  • Peru keys:
  • Philippines keys:
  • Russia keys: names: lnames:
  • Somalia keys: names:
  • South Korea keys: names: lnames:
  • Spain keys: names:
  • St. Kitts & Nevis keys:
  • Suriname keys:
  • Taiwan keys: lnames:
  • Thailand keys: lnames:
  • Turkey keys:
  • Tuvalu keys:
  • Ukraine keys: names: lnames:
  • United Arab Emirates keys: names: lnames:
  • United States keys: names:
  • Uruguay keys:
  • Venezuela keys:
  • Vietnam keys: lnames:

Regional Formats​

The following are all unique address formats in all regions. Note that not all components are used by all regions, the order may vary, and in some cases some literals are hard-coded.

FormatRegions
{Name}
{Organization}
{Address Lines}
{Postal Code} {Locality}
Algeria, Andorra, Bosnia & Herzegovina, Bulgaria, Cyprus, Czechia, Denmark, Dominican Republic, Estonia, Ethiopia, Georgia, Germany, Greece, Greenland, Guinea-Bissau, Iceland, Kosovo, Kuwait, Kyrgyzstan, Laos, Liberia, Madagascar, Montenegro, Morocco, Niger, North Macedonia, Norway, Paraguay, Poland, Portugal, Romania, San Marino, Senegal, Serbia, Slovakia, Svalbard & Jan Mayen, Tajikistan, Tanzania, Tunisia, Turkmenistan, Vatican City, Western Sahara, Zambia
{Name}
{Organization}
{Address Lines}
{Locality}
{Postal Code}
Afghanistan, Anguilla, Ascension Island, British Indian Ocean Territory, British Virgin Islands, Eswatini, Falkland Islands, Isle of Man, Kenya, Namibia, Pitcairn Islands, Sri Lanka, St. Helena, Sudan, Tristan da Cunha, Turks & Caicos Islands, United Kingdom
{Name}
{Organization}
{Address Lines}
{Locality} {Postal Code}
Bahrain, Bermuda, Bhutan, Brunei, Cambodia, Guam, Israel, Jordan, Lebanon, Lesotho, Maldives, Malta, Nepal, Saudi Arabia, St. Vincent & Grenadines
{Organization}
{Name}
{Address Lines}
{Postal Code} {Locality} {Sorting Code}
French Guiana, Guadeloupe, Martinique, Mayotte, New Caledonia, Réunion, St. Barthélemy, St. Martin, St. Pierre & Miquelon, Wallis & Futuna
{Name}
{Organization}
{Address Lines}
{Locality} {Administrative Area} {Postal Code}
American Samoa, Canada, Marshall Islands, Micronesia, Northern Mariana Islands, Palau, U.S. Outlying Islands, U.S. Virgin Islands
{Organization}
{Name}
{Address Lines}
{Locality} {Administrative Area} {Postal Code}
Australia, Christmas Island, Cocos (Keeling) Islands, Heard & McDonald Islands, Norfolk Island
{Name}
{Organization}
{Address Lines}
{Postal Code}
{Locality}
Albania, Ecuador, Mauritius, Oman
{Name}
{Organization}
{Address Lines}
{Postal Code} {Locality}
{Administrative Area}
Argentina, Cape Verde, Chile, Uzbekistan
{Organization}
{Name}
{Address Lines}
{Postal Code} {Locality}
Austria, Belgium, France, Netherlands
{Name}
{Organization}
{Address Lines}
{Postal Code} {Locality} {Administrative Area}
French Polynesia, Italy, Spain, Uruguay
{Name}
{Organization}
{Address Lines}
{Locality}
{Administrative Area}
Panama, Seychelles, Suriname, Tuvalu
{Name}
{Organization}
{Address Lines}
{Locality}, {Administrative Area} {Postal Code}
Barbados, Somalia, United States
{Name}
{Organization}
{Address Lines}
{Locality}
{Administrative Area}
{Postal Code}
Egypt, Russia, Ukraine
{Name}
{Organization}
{Address Lines}
{Locality}
{Administrative Area} {Postal Code}
Indonesia, Mongolia, Vietnam
{Name}
{Organization}
{Address Lines}
{Administrative Area}
Nauru, United Arab Emirates
{Name}
{Organization}
{Address Lines}
{Locality} {Sorting Code}
Burkina Faso, Malawi
{Name}
{Organization}
{Address Lines}
{Locality}, {Administrative Area}
Bahamas, St. Kitts & Nevis
{Name}
{Organization}
{Address Lines}
{Locality} {Postal Code}
{Administrative Area}
India, Peru
{Postal Code}
{Administrative Area}
{Locality}
{Address Lines}
{Organization}
{Name}
Kazakhstan, North Korea
{Name}
{Organization}
{Address Lines}
{Locality}, {Postal Code}
Latvia, Myanmar (Burma)
{Name}
{Organization}
{Address Lines}
{Postal Code}
{Locality}
{Administrative Area}
Armenia
{Organization}
{Name}
{Address Lines}
AX-{Postal Code} {Locality}
ÅLAND
Åland Islands
{Name}
{Organization}
{Address Lines}
AZ {Postal Code} {Locality}
Azerbaijan
{Name}
{Organization}
{Address Lines}
{Locality} - {Postal Code}
Bangladesh
{Organization}
{Name}
{Address Lines}
{Sublocality}
{Locality}-{Administrative Area}
{Postal Code}
Brazil
{Organization}
{Name}
{Address Lines}
{Postal Code}, {Locality}
{Administrative Area}
Belarus
{Organization}
{Name}
{Address Lines}
CH-{Postal Code} {Locality}
Switzerland
{Name}
{Organization}
{Sorting Code} {Address Lines} {Locality} {Sorting Code}
Côte d’Ivoire
{Postal Code}
{Administrative Area}{Locality}{Sublocality}
{Address Lines}
{Organization}
{Name}
China
{Name}
{Organization}
{Address Lines}
{Locality}, {Administrative Area}, {Postal Code}
Colombia
{Name}
{Organization}
{Address Lines}
{Administrative Area}, {Locality}
{Postal Code}
Costa Rica
{Name}
{Organization}
{Address Lines}
{Locality} {Administrative Area}
{Postal Code}
Cuba
{Organization}
{Name}
{Address Lines}
FI-{Postal Code} {Locality}
Finland
{Name}
{Organization}
{Address Lines}
FO{Postal Code} {Locality}
Faroe Islands
{Name}
{Organization}
{Address Lines}
{Locality}
GUERNSEY
{Postal Code}
Guernsey
{Name}
{Organization}
{Address Lines}
GIBRALTAR
{Postal Code}
Gibraltar
{Name}
{Organization}
{Postal Code} {Address Lines} {Locality}
Guinea
{Name}
{Organization}
{Address Lines}

{Locality}
{Postal Code}
South Georgia & South Sandwich Islands
{Name}
{Organization}
{Address Lines}
{Postal Code}- {Locality}
Guatemala
{Administrative Area}
{Locality}
{Address Lines}
{Organization}
{Name}
Hong Kong SAR China
{Name}
{Organization}
{Address Lines}
{Locality}, {Administrative Area}
{Postal Code}
Honduras
{Name}
{Organization}
{Address Lines}
HR-{Postal Code} {Locality}
Croatia
{Name}
{Organization}
{Address Lines}
HT{Postal Code} {Locality}
Haiti
{Name}
{Organization}
{Locality}
{Address Lines}
{Postal Code}
Hungary
{Name}
{Organization}
{Address Lines}
{Sublocality}
{Locality}
{Administrative Area}
{Postal Code}
Ireland
{Organization}
{Name}
{Address Lines}
{Locality}, {Administrative Area}
{Postal Code}
Iraq
{Organization}
{Name}
{Administrative Area}
{Locality}, {Sublocality}
{Address Lines}
{Postal Code}
Iran
{Name}
{Organization}
{Address Lines}
{Locality}
JERSEY
{Postal Code}
Jersey
{Name}
{Organization}
{Address Lines}
{Locality}
{Administrative Area} {Sorting Code}
Jamaica
〒{Postal Code}
{Administrative Area}
{Address Lines}
{Organization}
{Name}
Japan
{Name}
{Organization}
{Address Lines}
{Administrative Area}
{Locality}
Kiribati
{Administrative Area} {Locality}{Sublocality}
{Address Lines}
{Organization}
{Name}
{Postal Code}
South Korea
{Name}
{Organization}
{Address Lines}
{Administrative Area} {Postal Code}
Cayman Islands
{Organization}
{Name}
{Address Lines}
FL-{Postal Code} {Locality}
Liechtenstein
{Organization}
{Name}
{Address Lines}
LT-{Postal Code} {Locality}
Lithuania
{Organization}
{Name}
{Address Lines}
L-{Postal Code} {Locality}
Luxembourg
{Name}
{Organization}
{Address Lines}
MC-{Postal Code} {Locality} {Sorting Code}
Monaco
{Name}
{Organization}
{Address Lines}
MD-{Postal Code} {Locality}
Moldova
{Address Lines}
{Organization}
{Name}
Macao SAR China
{Name}
{Organization}
{Address Lines}
{Sublocality}
{Postal Code} {Locality}, {Administrative Area}
Mexico
{Name}
{Organization}
{Address Lines}
{Sublocality}
{Postal Code} {Locality}
{Administrative Area}
Malaysia
{Name}
{Organization}
{Address Lines}
{Postal Code} {Locality}{Administrative Area}
Mozambique
{Name}
{Organization}
{Address Lines}
{Sublocality}
{Locality} {Postal Code}
{Administrative Area}
Nigeria
{Name}
{Organization}
{Address Lines}
{Postal Code}
{Locality}, {Administrative Area}
Nicaragua
{Name}
{Organization}
{Address Lines}
{Sublocality}
{Locality} {Postal Code}
New Zealand
{Name}
{Organization}
{Address Lines}
{Locality} {Postal Code} {Administrative Area}
Papua New Guinea
{Name}
{Organization}
{Address Lines}
{Sublocality}, {Locality}
{Postal Code} {Administrative Area}
Philippines
{Name}
{Organization}
{Address Lines}
{Locality}-{Postal Code}
Pakistan
{Name}
{Organization}
{Address Lines}
{Locality} PR {Postal Code}
Puerto Rico
{Organization}
{Name}
{Address Lines}
SE-{Postal Code} {Locality}
Sweden
{Name}
{Organization}
{Address Lines}
SINGAPORE {Postal Code}
Singapore
{Name}
{Organization}
{Address Lines}
SI-{Postal Code} {Locality}
Slovenia
{Name}
{Organization}
{Address Lines}
{Postal Code}-{Locality}
{Administrative Area}
El Salvador
{Name}
{Organization}
{Address Lines}
{Sublocality} {Locality}
{Administrative Area} {Postal Code}
Thailand
{Name}
{Organization}
{Address Lines}
{Postal Code} {Locality}/{Administrative Area}
Turkey
{Postal Code}
{Administrative Area}{Locality}
{Address Lines}
{Organization}
{Name}
Taiwan
{Name}
{Organization}
{Address Lines}
{Locality} {Postal Code}, {Administrative Area}
Venezuela
{Name}
{Organization}
{Address Lines}
{Sublocality}
{Locality}
{Postal Code}
South Africa
{Name}
{Organization}
{Address Lines}
{Locality}
DEFAULT