Get started with Free ISO3166 Country Code API

An overview on ISO3166 Country Code

How do we identify or name countries on the internet? Country codes are necessary for identifying countries in software and on the internet. ISO3166 Country Code is published by the International Organisation for Standardisation in 1974. It is widely used by governments, businesses, and individuals around the world. Wonder what is an ISO3166 Country Code in detailed and what is it for? This article will show you an in-depth sight on ISO3166-1 (Country code), and provide you a detailed tutorial on creating your custom ISO3166 Country Code API to get the country name by ISO3166-1 country code or vice versa. Read on to learn more!

What exactly is ISO3166?

ISO3166 is the International Standard for country codes. It is designed to define internationally recognised codes of letters and/or numbers that we can use when we refer to countries and their subdivisions. In 1997, the ISO3166 had been divided into three parts: ISO3166-1 (country codes), ISO3166-2 (subdivisions codes) and ISO3166-3 (formerly used codes). 

This article would mainly focus on ISO3166-1 (country codes). Instead of expressing the country’s full name, using a ISO3166 Country Code can save the time and avoid errors as there are changes depending on the language being used. Though it does not define the name of the countries, the ISO3166 is used to create a combination of letters and/or numbers that are understood all over the world to identify countries.

For example, the Internet Assigned Numbers Authority (IANA) uses ISO3166-1 alpha-2 codes to create the country code top-level Domains (ccTLDs) today such as “.fr” for France, “.au” for Australia.

Additionally, the country codes provide a way to detect the location of the bank when sending money from one bank to another, and are used to identify the user’s nationality in machine-readable passports.

What are defined in ISO3166 Country Code API?

In ISO3166-1, each country or territory is defined using three sets of country codes. 

• ISO3166-1 Numeric code 
• ISO3166-1 Alpha-2 code 
• ISO3166-1 Alpha-3 code 

ISO3166-1 Numeric code is a three-digit country codes which are identical to those developed and maintained by the United Nations Statistics Division, with the advantage of script (writing system) independence, and hence useful for people or systems using non-Latin scripts.    

ISO3166-1 Alpha-2 is a two-letter country codes which are the most widely used of the three, and used most prominently for the Internet’s country code top-level domains (ccTLDs) (with a few exceptions).

ISO3166-1 Alpha-3 is a three-letter country codes which allow a better visual association between the codes and the country names than the alpha-2 codes.

What is an API?

We all know that there are somethings we just don’t want do it manually. That’s where APIs come in. An API, or application programming interface, is a set of rules and specifications that allow two software programs to communicate with each other. Developers can build applications that work seamlessly together and make it possible for end-users to complete complex tasks with just a few clicks. By using an API, you can save yourself time and effort of having to write your own code from scratch. Let’s take a closer look at what an API is and how you can use it in your own development projects. If you want to know more about what an API is, check this link out.

For example, imagine being able to book a flight, hotel, and rental car all in one place by using just a few taps on your smartphone. This would not be possible without APIs! As the world becomes increasingly interconnected, the importance of well-designed APIs will only continue to grow.

How do we get the country name using an ISO3166 Country Code API?

On the internet, there are thousands of website providing scrollable tables or lists, listing all countries with their corresponding country codes for searching. Turns out, it may take time to find one or multiple codes you need. Here the ISO3166 Country Code API comes in. Using an ISO3166 Country Code API can allow users to make conversion between the name of a country and its ISO 3166-1 country code by a few simple moves. Let’s get started to follow the step-by-step guide to create a sample ISO3166 Country Code API here. 

Why should you choose this server?

The API is supported by FabriXAPI, an All-in-one API Platform that supports API Needs and it is certified as “AWS Qualified Software” since 2022. You can register for an API portal for free, share and monetise APIs easily on the trustable platform certified by ISO27001.

Prerequisites

You will need a suitable ISO3166 Country Code API provider. Using ISO API’s ISO3166 Country Code API, you can proceed easily as follows :

1. Sign up for a Developer Account

You need to sign up to the API Portal in order to subscribe and access this API. For more information, please refer to “Register as a Developer“.

2. Active API Subscription

You need to subscribe to this API before consuming it. Many APIs come with a free trial plan so that you can experience the API functions provided free of charge. For more information, please refer to “Subscribe to APIs“.

3. API Credential

An API Key is required to access the API. It can be obtained in the Developer Admin Portal once you have completed the signup to FabriXAPI. For more information, please refer to “Create API Key“.

Features

• Code to Country
• Country to Code
• Get all codes
• Get all supported languages (ISO 639-1)
• Get all country names
• Codes Conversion
  • Alpha-3 to Alpha-2 code
  • Numeric to Alpha-2 code
  • Alpha-2 to Alpha-3 code
  • Numeric to Alpha-3 code
  • Alpha-3 to Numeric code
  • Alpha-2 to Numeric code

You may check out the full API documentation on the API Portal.

Design an attractive User Interface

Let’s start by giving the API a user-friendly User Interface(UI). Try the following HTML!

<div id="app">
  <div class="demo-description">
    <h2>ISO3166 Country Code</h2>
    <span>To protect your credentials.</span>
    <br>
    <span>DO NOT save this API Key in the code sandbox!!</span>
  </div>
  <div class="test-area">
    <div class="input-area">
      <span>API Key</span>
      <input
        type="text"
        placeholder="Input your key here"
        v-model="apikey"
      >
      <br>
       
      <span>Mode</span>
        <select v-model="mode">
          <option value="/name-by-code">Code to Name</option>
          <option value="/code-by-name">Name to Code</option>
          <option value="/alpha2-to-alpha3">Alpha2 to Alpha3</option>
          <option value="/alpha2-to-numeric">Alpha2 to Numeric</option>
          <option value="/alpha3-to-alpha2">Alpha3 to Alpha2</option>
          <option value="/alpha3-to-numeric">Alpha3 to Numeric</option>
          <option value="/numeric-to-alpha2">Numeric to Alpha2</option>
          <option value="/numeric-to-alpha3">Numeric to Alpha3</option>
        </select>
      <br>
 
      <template v-if="showCode">
        <span>Code</span>
        <input
          type="text"
          placeholder="Code"
          v-model="code"
        >
        <br>
      </template>
       
      <template v-if="showCountry">
        <span>Country</span>
        <input
          type="text"
          placeholder="Country"
          v-model="country"
        >
        <br>
      </template>
 
      <template v-if="showLang">
        <span>Language</span>
        <input
          type="text"
          placeholder="Language"
          v-model="lang"
        >
        <br>
      </template>
       
      <template v-if="showType">
        <span>Type</span>
          <select v-model="type">
            <option value="all">All</option>
            <option value="alias">Alias</option>
            <option value="official">Official</option>
          </select>
        <br>
      </template>
             
      <template v-if="showAlpha2">
        <span>Alpha2</span>
        <input
          type="text"
          placeholder="Alpha2"
          v-model="alpha2"
        >
        <br>
      </template>
       
      <template v-if="showAlpha3">
        <span>Alpha3</span>
        <input
          type="text"
          placeholder="Alpha3"
          v-model="alpha3"
        >
        <br>
      </template>
       
      <template v-if="showNumeric">
        <span>Numeric</span>
        <input
          type="text"
          placeholder="Numeric"
          v-model="numeric"
        >
        <br>
      </template>
       
      <button v-if="mode !== ''" v-on:click="convert">Convert</button>
    </div>
 
    <div class="output-area">
      <template v-if="error">
        <span v-html="error" />
      </template>
      <template v-else-if="!result">
        Fill in the API Key and select mode, then fill in the needed information and press "Convert".
      </template>
      <template v-else>
        <div v-html="result" />
      </template>
    </div>
  </div>
</div>

Apply the CSS on your design

And then add the following CSS. 

@import url('https://fonts.googleapis.com/css2?family=Open+Sans:wght@400;600&display=swap');
body {
  background: #20262E;
  padding: 20px;
  font-family: 'Open Sans', sans-serif;
}
  
#app {
  background: #fff;
  border-radius: 4px;
  padding: 20px;
  transition: all 0.2s;
  /* height: 400px; */
}
  
.demo-description {
  text-align: center;
  margin-bottom: 20px;
}
  
.demo-description h2 {
  font-weight: semibold;
  margin-bottom: 5px;
}
  
.demo-description span {
  color: #999999;
}
  
.test-area {
  display: flex;
}
  
.input-area {
  text-align: right;
}
  
.input-area span {
  display: inline-block;
  line-height: 48px;
  margin-right: 8px;
  text-align: right;
  width: 150px;
}
  
.input-area input, select {
  border: 1px solid #999999;
  border-radius: 3px;
  height: 30px;
  width: 150px;
  padding: 0 7px;
}
 
.input-area select {
  height: 32px;
  width: 166px;
}
  
.input-area input::placeholder {
  color: #d0d0d0;
}
  
.input-area button {
  background-color: #57abf0;
  border: 0;
  border-radius: 4px;
  color: #ffffff;
  font-weight: 600;
  margin-top: 15px;
  width: 166px;
  padding: 15px 10px;
}
  
.output-area {
  color: #505050;
  font-size: 14px;
  margin: 20px;
  margin-right: 0px;
  width: calc(100% - 350px);
}
  
@media screen and (max-width: 616px) {
  .input-area {
    text-align: center;
  }
 
  .input-area span {
    text-align: left;
  }
    
  .output-area {
    width: calc(100% - 150px);
  }
    
  .input-area button {
    width: 140px;
    padding: 10px 7px;
  }
}
  
.output-area svg {
  transform: scale(0.7) translateX(-30px) translateY(-95px);
}

Interact your UI with Vue.js

Now, you can add the following Vue.js script to make your custom country code-country name convertor.

const endpoint = 'https://trial-api-iso-3166-country-code-2dcq.gw.openapihub.com/iso3166-country-code';
 
new Vue({
  el: '#app',
  data() {
    return {
      apikey: '',
      mode: '',
      code: '',
      country: '',
      lang: '',
      type: '',
      alpha3: '',
      alpha3: '',
      numeric: '',
      result: '',
      error: ''
    }
  },
  computed: {
    showCode() {
      const inputCode = ['/name-by-code', '/code-by-name']
      return inputCode.includes(this.mode)
    },
    showCountry() {
      const inputCountry = ['/code-by-name']
      return inputCountry.includes(this.mode)
    },
    showLang() {
      const inputLang = ['/name-by-code', '/code-by-name']
      return inputLang.includes(this.mode)
    },
    showType() {
      const inputType = ['/name-by-code']
      return inputType.includes(this.mode)
    },
    showAlpha2() {
      const inputAlpha2 = ['/alpha2-to-alpha3', '/alpha2-to-numeric']
      return inputAlpha2.includes(this.mode)
    },
    showAlpha3() {
      const inputAlpha3 = ['/alpha3-to-alpha2', '/alpha3-to-numeric']
      return inputAlpha3.includes(this.mode)
    },
    showNumeric() {
      const inputNumeric = ['/numeric-to-alpha2', '/numeric-to-alpha3']
      return inputNumeric.includes(this.mode)
    }
  },
  methods: {
    convert: function() {
      const getCall = ['/name-by-code', '/code-by-name']
      const axiosConfig = {
        headers: {
          'content-type': 'application/json',
          'x-openapihub-key': this.apikey
        }
      }
 
      if (getCall.includes(this.mode)) {
        let params = {
          'code': this.code,
          'language': this.lang
        }
        if (this.country) {
          params.country = this.country
        }
        if (this.type) {
          params.type = this.type
        }
        axios.get(`${endpoint}${this.mode}`, {
            params: params,
            headers: axiosConfig.headers
          })
          .then(res => {
            this.error = ''
            this.result = `Result -<br>${res.data.toString().replaceAll(',', '<br>')}`
          }).catch(err => {
            this.error = `Error occurred -<br>${err.response.data.message}`
            console.log('Error', err.response.data.message)
          })
      } else {
        let requestBody = {}
        if (this.alpha2) {
          requestBody.alpha2 = this.alpha2
        }
        if (this.alpha3) {
          requestBody.alpha3 = this.alpha3
        }
        if (this.numeric) {
          requestBody.numeric = this.numeric
        }
        axios.post(`${endpoint}${this.mode}`, requestBody, axiosConfig)
          .then(res => {
            this.error = ''
            this.result = `Result -<br>${res.data}`
          }).catch(err => {
            this.error = `Error occurred -<br>${err.response.data.message}`
            console.log('Error', err.response.data.message)
          })
      }
    }
  }
})

Try the API right now!

Now that we have all the materials prepared. Let’s have a try on our work.

Simply fill in the form with API key. Choose the convert mode, input the data you got and press “Convert”. Swiftly, you can get your the country’s name or code you need! Let’s try converting an Alpha 2 code to an Alpha 3 code as an example.

And the output is as follows:

Conclusion

ISO3166 Country Code provides us a global standard to represent countries in our software products or on the internet. As a developer, it’s a good practice to be aware of ISO standards as it helps ensure that products and services are safe, reliable, and of good quality. By understanding what is ISO3166 Country Code and a simple method creating a custom ISO3166 Country Code API, you may now improve your software development workflow by getting the desired countries’ information easily.