iso3166-2-api 🌎

Frontend API for the iso3166-2 software and repo that returns a plethora of subdivision/regional data for all countries in the ISO 3166-2 standard. Built using the Python Flask framework and hosted on the Vercel platform.

The main API homepage and documentation is available via the URL: https://iso3166-2-api.vercel.app/api

• A demo of the software and API is available here.
• A Medium article that dives deeper into iso3166-2 is available here.

Table of Contents

• Introduction
• API
• Staying up to date
• Requirements
• Issues
• Contact
• References

Introduction

This repo contains the front and backend of the API created for the iso3166-2 repository. The API returns a plethora of subdivision data for all countries in the ISO 3166-2 standard. Utilising the custom-built iso3166-2 software that incorporates data from the ISO 3166-2. Built using the Python Flask framework and hosted on the Vercel platform.

iso3166-2 is a lightweight custom-built Python package, and accompanying API, that can be used to access all of the world's ISO 3166-2 subdivision data. Here, subdivision can be used interchangeably with regions/states/provinces etc. Currently, the package and API support subdivision data from 250 officially assigned code elements within the ISO 3166-1, with 200 of these countries having recognized subdivisions (50 entires have 0 subdivisions), totalling 5,039 subdivisions across the whole dataset. Transitional reservations are not included and only 4 of the exceptional reservations, that have now been officially assigned, are included: AX (Aland Islands), GG (Guernsey), IM (Isle of Man) and JE (Jersey) [3]. The ISO 3166-2 was first published in 1998 and as of November 2023 there are 5,039 codes defined in it [2].

The full list of additional subdivision data attributes supported are:

• Name (subdivision name)
• Local name (subdivision name in local language)
• Code (subdivision code)
• Parent Code (subdivision parent code)
• Type (subdivision type, e.g. region, state, canton, parish etc)
• Latitude/Longitude (subdivision coordinates)
• Flag (subdivision flag from iso3166-flag-icons repo)

The ISO 3166 standard by the ISO defines codes for the names of countries, dependent territories, special areas of geographical interest, consolidated into the ISO 3166-1 standard [1], and their principal subdivisions (e.g., provinces, states, departments, regions), which comprise the ISO 3166-2 standard [2]. The ISO 3166-1 was first published in 1974 and currently comprises 249 countries, 193 of which are sovereign states that are members of the United Nations [1].

API

The main API endpoint is:

https://iso3166-2-api.vercel.app/api

The other endpoints available in the API are:

• https://iso3166-2-api.vercel.app/api/all
• https://iso3166-2-api.vercel.app/api/alpha/<input_alpha>
• https://iso3166-2-api.vercel.app/api/country_name/<input_country_name>
• https://iso3166-2-api.vercel.app/api/subdivision/<input_subdivision>
• https://iso3166-2-api.vercel.app/api/name/<input_subdivision_name>
• https://iso3166-2-api.vercel.app/api/list_subdivisions

Six paths/endpoints are available in the API - /api/all, /api/alpha, /api/country_name, /api/subdivision, /api/name and /api/list_subdivisions.

• /api/all: get all of the ISO 3166 subdivision data for all countries.

• /api/alpha: get all of the ISO 3166 subdivision data for 1 or more inputted ISO 3166-1 alpha-2, alpha-3 or numeric country codes, e.g. /api/alpha/FR,DE,HU,ID,MA, /api/alpha/FRA,DEU,HUN,IDN,MAR and /api/alpha/428,504,638. A comma separated list of multiple alpha codes can also be input. If an invalid country code is input then an error will be returned.

• /api/country_name: get all of the ISO 3166 subdivision data for 1 or more inputted ISO 3166-1 country names, as they are commonly known in English, e.g. /api/country_name/France,Moldova,Benin. A comma separated list of country names can also be input. A closeness function is utilised so the most approximate name from the input will be used e.g. Sweden will be used if input is /api/country_name/Swede. If no country is found from the closeness function or an invalid name is input then an error will be returned.

• /api/subdivision: get all of the ISO 3166 subdivision data for 1 or more ISO 3166-2 subdivision codes, e.g /api/subdivision/GB-ABD. You can also input a comma separated list of subdivision codes from the same and or different countries and the data for each will be returned e.g /api/subdivision/IE-MO,FI-17,RO-AG. If the input subdivision code is not in the correct format then an error will be raised. Similarly if an invalid subdivision code that doesn't exist is input then an error will be raised.

• /api/name/: get all of the ISO 3166 subdivision data for 1 or more ISO 3166-2 subdivision names, e.g /api/name/Derry. You can also input a comma separated list of subdivision name from the same or different countries and the data for each will be returned e.g /api/name/Paris,Frankfurt,Rimini. A closeness function is utilised to find the matching subdivision name, if no exact name match found then the most approximate subdivisions will be returned. Some subdivisions may have the same name, in this case each subdivision and its data will be returned e.g /api/name/Saint George (this example returns 5 subdivisions). This endpoint also has the likeness score (?likeness=) query string parameter that can be appended to the URL. This can be set between 1 - 100, representing a % of likeness to the input name the return subdivisions should be, e.g: a likeness score of 90 will return fewer potential matches whose name only match to a high degree compared to a score of 10 which will create a larger search space, thus returning more potential subdivision matches. A default likeness of 100 (exact match) is used, if no matching subdivision is found then this is reduced to 90. If an invalid subdivision name that doesn't match any is input then an error will be raised.

• /api/list_subdivisions: get list of all the subdivision codes for all countries.

• /api: main homepage and API documentation.

The API documentation and usage with all useful commands and examples to the API is available on the API.md file.

A demo of the software and API is available here.

Staying up to date

An important thing to note about the ISO 3166-2 and its subdivision codes/names is that changes are made consistently to it, from a small subdivision name change to an addition/deletion of a whole subdivision. These changes can happen due to a variety of geopolitical and administrative reasons. Therefore, it's important that the iso3166-2 library and its dataset have the most up-to-date, accurate and reliable data. To achieve this, the custom-built iso3166-updates repo was created.

The iso3166-updates repo is another open-source software package and accompanying API that pulls the latest updates and changes for any and all countries in the ISO 3166 from a variety of data sources including the ISO website itself. A script is called every few months to check for any updates/changes to the subdivisions, which are communicated via the ISO's Online Browsing Platform [4], and will then be manually incorporated into the iso3166-2 and dataset. Please visit the repository home page for more info about the purpose and process of the software and API - iso3166-updates.

The list of ISO 3166 updates was last updated on June 2024. A log of the latest ISO 3166 updates can be seen in the UPDATES.md.

Requirements

• python >= 3.8
• flask >= 2.3.2
• requests >= 2.28.1
• iso3166 >= 2.1.1
• iso3166-2 >= 1.5.0
• unidecode >= 1.3.8
• thefuzz >= 0.22.1

Issues

Any issues, errors or enhancements can be raised via the Issues tab in the repository.

Contact

If you have any questions or comments, please contact [email protected] or raise an issue on the Issues tab.

Other ISO 3166 repositories

Below are some of my other custom-built repositories that relate to the ISO 3166 standard.

• iso3166-2: a lightweight custom-built Python package, and accompanying API, that can be used to access all of the world's ISO 3166-2 subdivision data. A plethora of data attributes are available per country and subdivision including: name, local name, code, parent code, type, lat/longitude and flag. Currently, the package and API supports data from 250 countries/territories, according to the ISO 3166-1 standard.
• iso3166-updates: software and accompanying API that checks for any updates/changes to the ISO 3166-1 and ISO 3166-2 country codes and subdivision naming conventions, as per the ISO 3166 newsletter (https://www.iso.org/iso-3166-country-codes.html) and Online Browsing Platform (OBP) (https://www.iso.org/obp/ui).
• iso3166-updates-api: frontend API for iso3166-updates.
• iso3166-flag-icons: a comprehensive library of over 3500 country and regional flags from the ISO 3166-1 and ISO 3166-2 standards.

References

[1]: ISO3166-1: https://en.wikipedia.org/wiki/ISO_3166-1
[2]: ISO3166-2: https://en.wikipedia.org/wiki/ISO_3166-2
[3]: ISO Country Codes Collection: https://www.iso.org/publication/PUB500001
[4]: ISO Country Codes: https://www.iso.org/iso-3166-country-codes.html
[5]: ISO3166-1 flag-icons repo: https://github.com/lipis/flag-icons
[6]: ISO3166-2 flag-icons repo: https://github.com/amckenna41/iso3166-flag-icons

Support

Back to top