Frontend RESTful API for the iso3166-2 software and repo that returns a plethora of bespoke, valuable and useful attributes for the >5000 subdivisions/regions 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

• Source code for main iso3166-2 software package is available here
• A demo of the software and API is available here
• A Medium article that dives deeper into iso3166-2 is available here

• Introduction
• Bespoke Features
• Usage
• Requirements
• Issues
• Contact
• References

This repo contains the front and backend of the RESTful API created to accompany the iso3166-2 repository. The API returns a plethora of bespoke, useful and valuable subdivision data for all countries in the ISO 3166-2 standard. Built using the Python Flask framework and hosted on the Vercel platform.

iso3166-2 is a lightweight custom-built Python package 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,049 subdivisions across the whole dataset.

The full list of subdivision data attributes supported are:

• Code - ISO 3166-2 subdivision code
• Name - subdivision name
• Local/other name - subdivision name in local language or any alternative name/nickname it is commonly known by
• 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; this is another ISO 3166 related custom-built dataset of over 3500 regional/subdivision flags
• History - historical updates/changes to the subdivision code and naming conventions, as per the custom-built iso3166-updates repo.

There are three main attributes supported by the software that make it stand out and add a significant amount of value and data per subdivision, in comparison to some the other iso3166-2 datasets, these are the local/other name, flag and history attributes.

One of the most important and bespoke attributes that the software supports, that many others do not, is the local/other name attribute. This attribute is built from a custom dataset of local language variants and alternative names/nicknames for the over 5000 subdivisions. In total there are >3700 local/other names for the >5000 subdivisions. Primarily, the attribute contains local language translations for the subdivisions, but many also include nicknames and alternative variants that the subdivision may be known by, either locally or globally.

For each local/other name, the ISO 639 3 letter language code is used to identify the language of the name. Some translations do not have available ISO 639 codes, therefore the Glottolog or other databases (e.g IETF) language codes are used. Some example local/other name entries are:

• Sindh (Pakistan PK-SD): "سِنْدھ (urd), Sindh (eng), SD (eng), Mehran/Gateway (eng), Bab-ul-Islam/Gateway of Islam (eng)"
• Central Singapore (Singapore SG-01): "Pusat Singapura (msa), 新加坡中部 (zho), மத்திய சிங்கப்பூர் (tam)"
• Bobonaro (East Timor TL-BO): "Bobonaru (tet), Buburnaru (tet), Tall eucalypt (eng)"
• Wyoming (USA US-WY) - "Equality State (eng), Cowboy State (eng), Big Wyoming (eng)"

The full dataset of local/other names is available in the repo here local_other_names.csv

The other equally important and bespoke/unique attribute that the software package supports is the flag attribute, which is a link to the subdivision's flag on the iso3166-flag-icons repo. This is another custom-built repository, (alongside iso3166-2 and iso3166-updates) that stores a rich and comprehensive dataset of over 3500 individual subdivision flags.

The flags repo uses the iso3166-2 software to get the full list of ISO 3166-2 subdivision codes which is kept up-to-date and accurate via the iso3166-updates software.

The history attribute has any applicable historical updates/changes to the individual subdivisions, if applicable. The data source for this is another custom-built software package previously mentioned iso3166-updates. This package keeps track of all the published changes that the ISO make to the ISO 3166 standard which include addition of new subdivisions, deletion of existing subdivisions or amendments to existing subdivisions. Thus iso3166-updates helps ensure that the data in the iso3166-2 package is also kept up-to-date and accurate. If any updates are found for the subdivision a short description of the change, it's publication date as well as its source will be included.

Please refer to the API.md file for API usage examples.

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

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

If you have any questions or comments, please contact amckenna41@qub.ac.uk or raise an issue on the Issues tab.

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

• iso3166-2: a lightweight custom-built Python package that can be used to access all of the world's ISO 3166-2 subdivision data. 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,049 subdivisions across the whole dataset.
• iso3166-updates: software and accompanying RESTful 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.

[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-2 flag-icons repo: https://github.com/amckenna41/iso3166-flag-icons

Back to top