iso3166-flags is a bespoke, verbose and comprehensive dataset of all ISO 3166-1 & ISO 3166-2 country and regional/subdivision codes flag icons in SVG format. The dataset currently has 250 country/territorial flags and 2,845 regional/subdivision flags.
| Total Flags | ISO3166-1 Flags | ISO3166-2 Flags | SVG | PNG | JPEG / JPG | Other | Total Dataset Size (MB) | ISO3166-1 Dataset Size (MB) | ISO3166-2 Dataset Size (MB) |
|---|---|---|---|---|---|---|---|---|---|
| 3,095 | 250 | 2,845 | 2,243 | 798 | 54 | 0 | 341.271 | 1.621 | 339.650 |
- Introduction
- Installation
- Usage
- Updates
- Directories
- Issues or Contributing
- Contact
- References
- Support
iso3166-flags is a comprehensive, verbose and bespoke repository of all ISO 3166-1 and ISO 3166-2 country and regional/subdivision flag icons, respectively. The flags list is according to the International Organisation for Standards that define codes for the names of countries, dependent territories, special areas of geographical interest, and their principal subdivisions [1].
Currently the dataset contains 250 ISO 3166-1 country/territorial flag icons and 2,845 ISO 3166-2 regional/subdivision flags.
The ISO 3166-1 flags are those of the names of countries and their subdivisions that can be broken into three sets of country codes:
- ISO 3166-1 alpha-2 – 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 (with a few exceptions).
- ISO 3166-1 alpha-3 – three-letter country codes which allow a better visual association between the codes and the country names than the alpha-2 codes.
- ISO 3166-1 numeric – 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.
The ISO 3166-2 icons are those of the names of countries and their subdivisions – Part 2: Country subdivision code, defines codes for identifying the principal subdivisions (e.g., provinces, states, departments, regions) of all countries coded in ISO 3166-1. [2].
The ISO 3166-3 icons are those of countries and their subdivisions – Part 3: Code for formerly used names of countries, defines codes for country names which have been deleted from ISO 3166-1 since its first publication in 1974. This section of the ISO 3166 is not utilised in this repo.
iso3166-flags is a part of a larger suite of my custom-built and bespoke applications that utilise the ISO 3166 country and subdivision codes. The primary application is iso3166-2 which is is a structured lightweight custom-built Python package and dataset, and accompanying RESTful API, that can be used to access all of the world's ISO 3166-2 subdivision data.
One of the attributes in the iso3166-2 software package is the flag attribute - the subdivisions offical flag. When creating this dataset, there was no accurate or widely available dataset of the world's thousands of regional flags, so I created one!
The whole project can be cloned from git:
git clone https://github.com/amckenna41/iso3166-flags.git
The ISO 3166-1 and ISO 3166-2 are also split into branches and be downloaded seperately:
git clone -b iso3166-1-flags https://github.com/amckenna41/iso3166-flags.git
OR
git clone -b iso3166-2-flags https://github.com/amckenna41/iso3166-flags.git
Install via npm or yarn (not implemented yet):
npm install --dev iso3166-flags
yarn add --dev iso3166-flags
The flags can be implemented in-line by referencing the CSS class of the respective flag using the ISO 3166-1 or ISO 3166-2 CSS file. For ISO 3166-1 icons add the classes .fi and .fi-xx (where xx is the ISO 3166-1-alpha-2 code of a country) to an empty <span> [5]. To add a squared version flag additionally add the class fis.
For example, adding the normal and squared flags for Andorra, Denmark & Panama:
<span class="fi fi-ad"></span> <span class="fi fi-ad fis"></span>
<span class="fi fi-dk"></span> <span class="fi fi-dk fis"></span>
<span class="fi fi-pa"></span> <span class="fi fi-pa fis"></span>For ISO 3166-2 icons add the classes .fi and .fi-xx-yy (where xx is the ISO 3166-1-alpha-2 code of a country and yy is the ISO 3166-2 code, both in lower-case) to an empty <span> [2].
For example, adding the Hungarian county of Heves (HU-HE), the South Sudanese state of Eastern Equatoria (SS-EE) & the Taiwanese county of Miaoli (TW-MIA):
<span class="fi fi-hu-he"></span> <span class="fi fi-hu-he fis"></span>
<span class="fi fi-ss-ee"></span> <span class="fi fi-ss-ee fis"></span>
<span class="fi fi-tw-mia"></span> <span class="fi fi-tw-mia fis"></span>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 for a variety of geopolitical and administrative reasons. Therefore, it's important that this library and its JSON 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 RESTful 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 periodically 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 this repo. 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 November 2024 (the last published ISO subdivision change). A log of the latest ISO 3166 updates can be seen in the UPDATES.md file.
/iso3166-1-flags- flags of all country/territories according to the ISO 3166-1 standard./iso3166-2-flags- flags of all regions/subdivisions within countries/territories according to the ISO 3166-2 standard./css- css scripts for integrating the flags into front-end projects./scripts- a series of Python and bash scripts created for generating the CSS and README files for each country folder, as well as to export various metdata for the datasets./tests- unit tests for scripts and flags./iso3166-flags-metadata- metadata files for the ISO 3166-1 and ISO 3166-2 flags.
Below are some of my other custom-built repositories that relate to the ISO 3166 standard! ⚡
- iso3166-2: a lightweight custom-built bespoke Python package, dataset, 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 and >5000 subdivisions, according to the ISO 3166-2 standard.
- iso3166-2-api: frontend RESTful API for iso3166-2.
- 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 RESTful API for iso3166-updates.
Any issues, bugs or enhancements can be raised via the Issues tab in the repository. If you would like to contribute any functional/feature changes to the project, please make a Pull Request.
If you have any questions, comments or suggestions, please contact [email protected] or raise an issue in the Issues tab.
[1]: https://en.wikipedia.org/wiki/ISO_3166
[2]: https://en.wikipedia.org/wiki/ISO_3166-2
[3]: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
[4]: https://www.iso.org/obp/ui/#
