Address Formats by Country: JSON Templates to Download

This article provides a practical resource for developers, data researchers, and analysts: a collection of international address formats presented in a JSON format, ready for direct integration into your applications.

It's worth noting that these same address formats are utilized in the Geoapify Geocoding API, specifically within the formatted field. So, whether you're working on the web, mobile, or backend systems, these address format templates offer a standardized approach to handling global address data. They can be used for form auto-completion, validation, and localization, ensuring your application effectively manages and processes address information from different countries.

The formats cover various regions, including North America, Europe, Asia, Latin America, Africa, and the Middle East, making your software genuinely international in its reach.

Common Components of an Address

A typical international address consists of several key elements, each playing a role in pinpointing a specific location. While the order and usage of these elements can vary by country, they generally include:

1. [contact_name]: The name of the individual or entity intended to receive the mail or delivery.
2. [house]: The name or identifier of the building or residence.
3. [house_number]: The specific number assigned to the building on a street.
4. [road]: The name of the street or road.
5. [settlement_part]: A subdivision within a town or city, like a neighborhood or borough.
6. [settlement]: The town, city, or village where the address is located.
7. [postcode]: A postalcode (ZIP code) (numeric, alphanumeric, or otherwise) used for sorting and delivering mail.
8. [region_part]: A smaller administrative area within a larger region, such as a county or district.
9. [region]: A larger administrative area, like a state, province, or region.
10. [country]: The country in which the address is located, crucial for international mail.

It's important to mention that in addressing systems, especially when dealing with a global user base, it's crucial to recognize that not all address components are always used, and some may be replaced or extended with alternate or additional information:

• Skipped Components: In certain addresses, some components might be omitted. For example, rural or less formal addresses might not include a [house_number] but could use a street crossing or a landmark as a point of reference. In such cases, the address system should be flexible enough to handle these variations without compromising the location's accuracy.
• Extended Components: Often, a single address component may need to be expanded to capture the full detail of a location. For example:
  • In some regions, particularly in rural or semi-rural areas, the [settlement] might be a combination of a hamlet and a village name to provide clearer identification. This is common where smaller communities are closely linked or not well-known on their own.
  • Similarly, [region] and [region_part] might include several terms to accurately describe the administrative divisions, especially in countries with complex local governance structures.

For further in-depth understanding and exploration of the complexities of global addressing systems, you can refer to the Wikipedia page on addresses. This resource offers a broad overview of different addressing formats, practices, and their significance in various regions around the world. It's a valuable reference for anyone looking to deepen their knowledge about international address structures.

Understanding Variations in Global Address Formats

Address formats around the world exhibit significant variations, reflecting diverse postal systems and cultural practices. Here are the main distinguishing features of global address formats:

1. Starting Point of the Address:

   • Country First: In some regions, addresses begin with the [country] name, followed by progressively more specific details down to the street and [contact_name].
   • Contact Name First: Conversely, in many Western countries like the United States, the address starts with the [contact_name] and proceeds from the specific (house number and street) to the more general (country).

2. Street Name and House Number Ordering:

   • Street Name Followed By House Number: Some address systems, like those in parts of Europe, list the [road] name first followed by the [house_number]. This format is more common in places where streets have well-defined names.
   • House Number Followed By Road: Conversely, in many other regions, including the United States, addresses typically start with the [house_number] followed by the [road]. This format often aligns with the way people commonly describe locations verbally in these regions.

3. Placement of the Postal Code (ZIP code):

   • Before the Settlement Name: In countries like the UK and Germany, the [postcode] often precedes the city or town name. This format is particularly efficient for mail sorting.
   • After the Settlement Name: In contrast, in countries like the United States and Canada, the [postcode] follows the city or town name.
   • End of the Address: In some addressing formats, particularly in certain Asian countries, the [postcode] is positioned at the end of the address.

Top 10 Address Templates and Corresponding Countries

In this section, we provide a selection of the 10 most common address templates representative of various global formats. These templates illustrate the diversity in address structuring across different countries, showcasing how each component is utilized. Accompanying each template is a list of countries where that particular format is predominantly used.

1. Contact Name, House, Street Number, Postcode/ZIP Settlement, Country

[contact_name]
[house]
[road] [house_number]
[postcode] [settlement]
[country]

• Format: [contact_name]\n[house]\n[road] [house_number]\n[postcode] [settlement]\n[country]
• Building Address: [house], [road] [house_number], [postcode] [settlement], [country]
• Corresponding countries: Albania, Austria, Åland Islands, Bosnia and Herzegovina, Belgium, Bonaire, Sint Eustatius and Saba, Bouvet Island, Switzerland, Chile, Cape Verde, Cyprus, Czech Republic, Germany, Denmark, Estonia, Ethiopia, Finland, Faroe Islands, Georgia, Greenland, Greece, Guinea-Bissau, Honduras, Croatia, Haiti, Israel, Iceland, Jordan, Liechtenstein, Liberia, Lithuania, Montenegro, North Macedonia, Netherlands, Norway, Poland, Palestine, Portugal, Palau, Paraguay, Romania, Serbia, Sudan, Sweden, Slovenia, Svalbard and Jan Mayen, Tajikistan, Turkey, Uruguay

Example

Sophie Peeters
Avenue Louise 50
1050 Bruxelles
Belgium

2. Contact Name, House, Street Number, Settlement, Country

[contact_name]
[house]
[road] [house_number]
[settlement]
[country]

• Format: [contact_name]\n[house]\n[road] [house_number]\n[settlement]\n[country]
• Building Address: [house], [road] [house_number], [settlement], [country]
• Corresponding countries: Aruba, Burundi, Bolivia, Central African Republic, Cameroon, Curaçao, Western Sahara, Eritrea, Grenada, Equatorial Guinea, Kiribati, Saint Lucia, Libya, Mali, Macao, Qatar, Solomon Islands, South Sudan, Sao Tome and Principe, Sint Maarten, Timor-Leste, Saint Vincent and the Grenadines, Vanuatu, Samoa

Example

Margaret Roberts
Lucas Street 17
St. George's
Grenada

3. Contact Name, House, Number Street, Settlement Part, Settlement Postcode/ZIP, Country

[contact_name]
[house]
[house_number] [road]
[settlement_part]
[settlement][postcode]
[country]

• Format: [contact_name]\n[house]\n[house_number] [road]\n[settlement_part]\n[settlement][postcode]\n[country]
• Building Address: [house], [house_number] [road], [settlement_part], [settlement][postcode], [country]
• Corresponding countries: British Indian Ocean Territory, Cambodia, Falkland Islands (Malvinas), Guernsey, Isle of Man, Jamaica, Jersey, New Zealand, Saint Helena, South Georgia and the South Sandwich Islands, Sri Lanka, Taiwan, Taiwan (English), Tokelau, Turks and Caicos Islands, United Kingdom

Example

Sarah Wilson
Hillcrest Villa
76 Queen Street
Auckland Central
Auckland 1010
New Zealand

4. Contact Name, House, Number Street, Postcode/ZIP Settlement, Country

[contact_name]
[house]
[house_number] [road]
[postcode] [settlement]
[country]

• Format: [contact_name]\n[house]\n[house_number] [road]\n[postcode] [settlement]\n[country]
• Building Address: [house], [house_number] [road], [postcode] [settlement], [country]
• Corresponding countries: Andorra, Azerbaijan, Saint Barthélemy, Algeria, France, French Guiana, Guadeloupe, Luxembourg, Morocco, Monaco, Saint Martin, Martinique, New Caledonia, French Polynesia, Saint Pierre and Miquelon, Réunion, Senegal, French Southern and Antarctic Lands, Tunisia, Wallis and Futuna, Mayotte, Zambia

Example

Clément Dupont
Le Moulin
42 Rue du Faubourg Saint-Antoine
75012 Paris
France

5. Contact Name, House, Number Street, Settlement, Country

[contact_name]
[house]
[house_number] [road]
[settlement]
[country]

• Format: [contact_name]\n[house]\n[house_number] [road]\n[settlement]\n[country]
• Building Address: [house], [house_number] [road], [settlement], [country]
• Corresponding countries: Antigua and Barbuda, Barbados, Belize, Côte d'Ivoire (Ivory Coast), Cook Islands, Djibouti, Dominica, Fiji, Ghana, Gibraltar, Gambia, Guyana, Montserrat, Malawi, Nauru, Niue, Rwanda, Seychelles, Sierra Leone, Tonga, Uganda, Zimbabwe.

Example

Jason Martin
Villa #4
10 Fig Tree Drive
Saint John's
Antigua and Barbuda

6. Contact Name, House, Number Street, Settlement, Region Postcode/ZIP, Country

[contact_name]
[house]
[house_number] [road]
[settlement], [region] [postcode]
[country]

• Format: [contact_name]\n[house]\n[house_number] [road]\n[settlement], [region] [postcode]\n[country]
• Building Address: [house], [house_number] [road], [settlement], [region] [postcode], [country]
• Corresponding countries: American Samoa, Canada, Federated States of Micronesia, Guam, Marshall Islands, Northern Mariana Islands, Puerto Rico, United States Minor Outlying Islands, United States, U.S. Virgin Islands.

Example

John Smith
Lakeview Apartment
2400 Sixth St NW
Washington, D.C. 20059
United States

7. Contact Name, House, Number Street, Settlement Postcode/ZIP, Country

[contact_name]
[house]
[house_number] [road]
[settlement] [postcode]
[country]

• Format: [contact_name]\n[house]\n[house_number] [road]\n[settlement] [postcode]\n[country]
• Building Address: [house], [house_number] [road], [settlement] [postcode], [country]
• Corresponding countries: Bahrain, Bermuda, Cayman Islands, Lebanon, Lesotho, Maldives, Namibia, Singapore, Slovakia.

Example

Ling Hu
Marina Bay Suites
10 Bayfront Avenue
Singapore 018956
Singapore

8. Contact Name, House, Number, Street, Settlement, Country

[contact_name]
[house]
[house_number], [road]
[settlement]
[country]

• Format: [contact_name]\n[house]\n[house_number], [road]\n[settlement]\n[country]
• Building Address: [house], [house_number], [road], [settlement], [country]
• Corresponding countries: Benin, Democratic Republic of the Congo, Republic of the Congo, Mauritania, Mauritius, Togo, Yemen

Example

Joseph Kabila
Villa Mango
45, Avenue Lumumba
Kinshasa
Democratic Republic of the Congo

9. Contact Name, House, Street Number, Settlement Part, Settlement, Country

[contact_name]
[house]
[road] [house_number]
[settlement_part]
[settlement]
[country]

• Format: [contact_name]\n[house]\n[road] [house_number]\n[settlement_part]\n[settlement]\n[country]
• Building Address: [house], [road] [house_number], [settlement_part], [settlement], [country]
• Corresponding countries: Afghanistan, Botswana, North Korea (Democratic People's Republic of Korea), Nicaragua, Somalia, Suriname, Chad.

Example

Mohammad Azizi
Zanbaq Square 12
Wazir Akbar Khan
Kabul
Afghanistan

10. Contact Name, House, Number Street, Settlement Region Postcode/ZIP, Country

[contact_name]
[house]
[house_number] [road]
[settlement] [region] [postcode]
[country]

• Format: [contact_name]\n[house]\n[house_number] [road]\n[settlement] [region] [postcode]\n[country]
• Building Address: [house], [house_number] [road], [settlement] [region] [postcode], [country]
• Corresponding countries: Australia, Cocos (Keeling) Islands, Christmas Island, Heard Island and McDonald Islands, Norfolk Island.

Example

Olivia Johnson
The Blue Cottage
47 Boundary Street
Brisbane Queensland 4000
Australia

Tailored Address Templates by Country

This resource, complete with a convenient download link for a JSON file, is an invaluable tool for developers and data analysts seeking to accurately integrate international address standards into their applications.

Download the complete JSON file of country-specific address formats >>

Programmatic Address Formatting

Using An NPM Library

In the world of software development, handling addresses programmatically is a common requirement, especially for applications that deal with international users. One efficient way to tackle this challenge is by using the npm package @fragaria/address-formatter. This library offers a robust solution for formatting addresses in a way that adheres to the specific conventions of various countries:

• Country-Specific Formatting: The library excels in recognizing and applying the appropriate address format based on the country. You can input address components, including various levels of settlements, and @fragaria/address-formatter will automatically format the address in the correct order and structure as per the country 's standard.
• Intelligent Settlement Handling: Whether your address data includes city names, village names, or any other form of settlements, this package is designed to format them correctly according to the regional norms. This is particularly useful when dealing with addresses from countries where multiple types of settlements (like cities, towns, hamlets) might be involved.
• State and County Abbreviations: A notable feature of @fragaria/address-formatter is its ability to handle abbreviations for states, provinces, and counties. The library contains a comprehensive list of these abbreviations. So, if your application provides the full name of a state or county, the library can automatically convert it to its standard abbreviation, if that 's the norm for the respective country 's address format.

Using @fragaria/address-formatter is straightforward. After installing the package in your project, you can format an address object by simply passing it to the library's formatting function:

Example 1: Formatting a US Address

import addressFormatter from '@fragaria/address-formatter';

const usAddress = {
  house_number: '1600',
  road: 'Pennsylvania Avenue NW',
  city: 'Washington',
  state: 'DC',
  postcode: '20500',
  country: 'United States'
};

console.log(addressFormatter.format(usAddress));

This will output:

1600 Pennsylvania Avenue NW
Washington, DC 20500
United States

Example 2: Formatting a UK Address

const addressFormatter = require('@fragaria/address-formatter');

const ukVillageAddress = {
  house_number: '12',
  road: 'High Street',
  village: 'Stow-on-the-Wold',
  postcode: 'GL54 1AB',
  country: 'United Kingdom'
};

console.log(addressFormatter.format(ukVillageAddress));

This will output:

12 High Street
Stow-on-the-Wold
GL54 1AB
United Kingdom

Example 3: Formatting a German Address

const germanSmallCityAddress = {
  house_number: '4',
  road: 'Hauptstraße',
  city: 'Cochem',
  postcode: '56812',
  country: 'Germany'
};

console.log(addressFormatter.format(germanSmallCityAddress));

This will output:

Hauptstraße 4
56812 Cochem
Germany

Example 4: Formatting a French Address

const frenchVillageAddress = {
  house_number: '22',
  road: 'Rue du Moulin',
  village: 'Eguisheim',
  postcode: '68420',
  country: 'France'
};

console.log(addressFormatter.format(frenchVillageAddress));

This will output:

22 Rue du Moulin
68420 Eguisheim
France

Using Geocoding API for Address Formatting

Geocoding APIs, such as the Geoapify Geocoding API, provide a dynamic approach to format addresses. THe API is particularly useful for applications that need to handle a large volume of addresses from multiple countries.

Here's how Geocoding APIs can enhance address formatting:

• Dynamic Address Resolution: Geocoding API can interpret and format addresses even when some components are missing or in a non-standard order.
• Localization and Accuracy: The API includes localization feature, ensuring addresses are formatted correctly for the intended country, considering local norms and postal requirements.
• Ease of Integration: APIs offer seamless integration with various programming languages and frameworks, making them a versatile choice for different types of applications.

Example

Suppose you want to geocode an address in Paris, France. the code with API call might look something like this:

fetch("https://api.geoapify.com/v1/geocode/search?text=25%20Rue%20Poulin%2C%2093100%20Montreuil%2C%20France&format=json&apiKey=YOUR_API_KEY")
  .then(response => response.json())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

The API response for the above request would typically be in JSON format, providing detailed information about the address:

{
  "results": [
    {
      "country": "France",
      "country_code": "fr",
      "region": "Metropolitan France",
      "state": "Ile-de-France",
      "county": "Seine-Saint-Denis",
      "city": "Montreuil",
      "municipality": "Bobigny",
      "postcode": "93100",
      "suburb": "Villiers - Barbusse",
      "street": "Rue Poulin",
      "housenumber": "25",
      "lon": 2.442039,
      "lat": 48.871062,
      "state_code": "IDF",
      "state_COG": "11",
      "result_type": "building",
      "formatted": "25 Rue Poulin, 93100 Montreuil, France",
      "address_line1": "25 Rue Poulin",
      "address_line2": "93100 Montreuil, France",
      ...
    }
  ],
  "query": {
    "text": "25 Rue Poulin, 93100 Montreuil, France",
    "parsed": {
      "housenumber": "25",
      "street": "rue poulin",
      "postcode": "93100",
      "city": "montreuil",
      "country": "france",
      "expected_type": "building"
    }
  }
}

FAQ