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→nameO→Organization→organizationA→Address Lines→address-line1throughaddress-line3D→Sublocality→address-level3C→Locality→address-level2S→Administrative Area→address-level1Z→Postal Code→postal-codeX→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, Taiwan, 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.
| Fields | Regions |
|---|---|
| address-line, city, postal | Afghanistan, 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, 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, Lebanon, Lesotho, Liberia, Liechtenstein, Luxembourg, Madagascar, Maldives, Malta, Mauritius, Moldova, Montenegro, Morocco, Myanmar (Burma), Namibia, Nepal, Netherlands, Niger, North Macedonia, Oman, Paraguay, Pitcairn Islands, Poland, Portugal, 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, city | Angola, 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, province | Argentina, Armenia, Belarus, Canada, Chile, Christmas Island, Cocos (Keeling) Islands, Costa Rica, Cuba, Egypt, El Salvador, Estonia, Heard & McDonald Islands, Indonesia, Iraq, Italy, Kazakhstan, Latvia, Lithuania, Mongolia, Mozambique, Norfolk Island, North Korea, Papua New Guinea, Romania, Somalia, Spain, Uruguay, Uzbekistan, Vietnam |
| address-line, city, postal, sorting-code | French Guiana, Guadeloupe, Martinique, Mayotte, Monaco, New Caledonia, Réunion, St. Barthélemy, St. Martin, St. Pierre & Miquelon, Wallis & Futuna |
| address-line, city, state, zip | American Samoa, Marshall Islands, Micronesia, Northern Mariana Islands, Palau, U.S. Outlying Islands, U.S. Virgin Islands, United States |
| address-line, city, island | Bahamas, Kiribati, Seychelles, St. Kitts & Nevis, Tuvalu |
| address-line, post_town, postal | Norway, Svalbard & Jan Mayen, Sweden, United Kingdom |
| address-line, city, postal, suburb | New Zealand, Pakistan, South Africa |
| address-line, city, sorting-code | Burkina Faso, Malawi |
| address-line, city, neighborhood, postal, state | Brazil, Mexico |
| address-line, city, island, postal | Cape Verde, French Polynesia |
| address-line, postal | Gibraltar, Singapore |
| address-line, city, zip | Guam, Puerto Rico |
| address-line, city, department, postal | Honduras, Nicaragua |
| address-line, district | Nauru, Syria |
| address-line, city, province | Panama, Suriname |
| address-line, district, postal, province | Peru, Turkey |
| address-line, city, postal, province, suburb | Philippines, Thailand |
| address-line, city, oblast, postal | Russia, Ukraine |
| address-line, emirate | United Arab Emirates |
| address-line, postal, state, suburb | Australia |
| address-line, city, parish, postal | Barbados |
| address-line, city, sorting-code, sorting-code | Côte d’Ivoire |
| address-line, city, district, postal, province | China |
| address-line, city, department, postal, suburb | Colombia |
| address-line, area, district | Hong Kong SAR China |
| address-line, city, county, eircode, townland | Ireland |
| address-line, city, pin, state | India |
| address-line, city, neighborhood, postal, province | Iran |
| address-line, city, parish, sorting-code | Jamaica |
| address-line, postal, prefecture | Japan |
| address-line, city, district, do_si, postal | South Korea |
| address-line, island, postal | Cayman Islands |
| address-line | Macao SAR China |
| address-line, city, postal, state, village_township | Malaysia |
| address-line, city, postal, state, suburb | Nigeria |
| address-line, district, postal | Sudan |
| address-line, county, district, postal | Taiwan |
| address-line, city, postal, state | Venezuela |
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:
- Colombia keys:
- 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.
| Format | Regions |
|---|---|
{Name}
{Organization}
{Address Lines}
{Postal Code} {Locality} | Algeria, Andorra, Bosnia & Herzegovina, Bulgaria, Cyprus, Czechia, Denmark, Dominican Republic, Ethiopia, Georgia, Germany, Greece, Greenland, Guinea-Bissau, Iceland, Kosovo, Kuwait, Kyrgyzstan, Laos, Liberia, Madagascar, Montenegro, Morocco, Niger, North Macedonia, Norway, Paraguay, Poland, Portugal, 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} {Administrative Area} | Estonia, French Polynesia, Italy, Spain, Uruguay |
{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}
{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}
{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}
{Sublocality}
{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} {Administrative Area} | Lithuania |
{Organization}
{Name}
{Address Lines}
L-{Postal Code} {Locality} | Luxembourg |
{Name}
{Organization}
{Address Lines}
{Administrative Area}
{Locality}, {Postal Code} | Latvia |
{Name}
{Organization}
{Address Lines}
MC-{Postal Code} {Locality} {Sorting Code} | Monaco |
{Name}
{Organization}
{Address Lines}
MD-{Postal Code} {Locality} | Moldova |
{Name}
{Organization}
{Address Lines}
{Locality}, {Postal Code} | Myanmar (Burma) |
{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}
{Sublocality}
{Locality}-{Postal Code} | Pakistan |
{Name}
{Organization}
{Address Lines}
{Locality} PR {Postal Code} | Puerto Rico |
{Name}
{Organization}
{Address Lines}
{Postal Code} {Administrative Area} {Locality} | Romania |
{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 |