ISO 3166-2 🌎

iso3166-2 is a lightweight custom-built Python wrapper, and accompanying API, for the RestCountries API (https://restcountries.com/) which includes an abundance of information about all ISO 3166 countries/territories 🌎. But this package also includes information about all countrys' ISO 3166-2 subdivision codes & names, which is absent from RestCountries. Currently, the package and API supports data from 250 countries/territories, according to the ISO 3166-1 standard. The full list of attributes that are supported can be seen in the ATTRIBUTES.md file. Available via a Python software package or an API; a demo of both is available here. There is also a demo available for the get_iso3166_2.py script that exports all the ISO 3166-2 from the various data sources, available here.

Table of Contents

• Introduction
• Requirements
• Installation
• Usage
• Issues
• Contact
• References

Introduction

iso3166-2 is a custom-built Python wrapper for the RestCountries (https://restcountries.com/) API which includes an abundance of information about all ISO 3166 countries/territories. But this package also includes information about all countrys' ISO 3166-2 subdivision codes & names, which is absent from RestCountries. The International Organisation for Standards defines codes for the names of countries, dependent territories, special areas of geographical interest, and their principal subdivisions [1].

The ISO 3166-2 defines codes for identifying the principal subdivisions (e.g., provinces, states, municipality etc) of all countries coded in the ISO 3166-1. The official name of the standard is "Codes for the representation of names of countries and their subdivisions – Part 2: Country subdivision code." It was first published in 1998 [2]. As of 29 November 2022 there are 5,043 codes defined in ISO 3166-2. For some countries, codes are defined for more than one level of subdivisions.

The full list of attributes/fields available in iso3166-2 can be viewed in the ATTRIBUTES.md file.

Currently, this package and accompanying API supports data from 250 countries/territories, as listed in the ISO 3166-1 standard.

Latest Updates

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 reasons. Therefore, it's important that this library and its JSONs have the most up-to-date 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. The API is called every few months to check for any updates, which are communicated 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.

Requirements

• python >= 3.8
• iso3166 >= 2.1.1

Requirements (get_iso3166_2.py)

• python >= 3.8
• requests >= 2.28.1
• iso3166 >= 2.1.1
• pycountry >= 22.3.5
• googlemaps >= 4.10.0
• tqdm >= 4.64.0
• natsort >= 8.4.0

Installation

Install the latest version of iso3166-2 via PyPi using pip:

pip3 install iso3166-2 --upgrade

Installation from source:

git clone -b master https://github.com/amckenna41/iso3166-2.git
cd iso3166_2
python3 setup.py install

Usage

There are two main JSONs that iso3166-2 utilises, iso3166-2.json and iso3166-2-min.json. The first JSON contains all country information, including all data pulled from the restcountries API as well as the country's subdivision data, this file is about 3.3 MB. The iso3166-2-min.json file is a minimised version of the first JSON, only containing each country's ISO3166-2 subdivision data, this file is 1.5 MB. In the main module iso3166_2.py, all data from the iso3166-2.json is accessible via the iso.country object and all data from the iso3166-2-min.json is accessible via the iso.subdivisions object.

Import ISO3166_2 class and access the country and subdivision data:

import iso3166_2 as iso

#access all country data
canada_iso3166_2 = iso.country["CA"]
denmark_iso3166_2 = iso.country["DK"]
estonia_iso3166_2 = iso.country["EE"]
fiji_haiti_guyana_iso3166_2 = iso.country["FJ, HT, GY"]

#access all country subdivision data
canada_iso3166_2 = iso.subdivisions["CA"]
denmark_iso3166_2 = iso.subdivisions["DK"]
estonia_iso3166_2 = iso.subdivisions["EE"]
fiji_haiti_guyana_iso3166_2 = iso.subdivisions["FJ, HT, GY"]

Get country data:

import iso3166_2 as iso

canada_iso3166_2.name #country name
denmark_iso3166_2.currencies #country currencies
estonia_iso3166_2.capital #country capital 
fiji_iso3166_2.population #country population 

Get a specific subdivision's info:

import iso3166_2 as iso

canada_iso3166_2.subdivisions['CA-AB'] #Alberta subdivision
denmark_iso3166_2.subdivisions['DK-81'] #Nordjylland subdivision
estonia_iso3166_2.subdivisions['EE-899'] #Viljandi subdivision
fiji_iso3166_2.subdivisions['FJ-03'] #Cakaudrove subdivision 

Usage (get_iso3166_2.py)

The script get_iso3166_2.py is used for gathering and exporting all country and subdivision data to the mentioned JSONs. It uses the restcountries api as well as the pycountry and googlemaps packages to gather and export all the required info. Calling the script using its default parameters will gather all the data for all countries, but the alpha2_codes parameter can be set to pull the updates for a specific list of one or more countries (the alpha-3 code can also be input, which is then converted into its 2 letter alpha-2 counterpart).

To download all of the latest ISO 3166-2 subdivision data for all countries, run the get_iso3166_2.py in a terminal or command line below; (the script takes around 2 hours to execute):

python3 get_iso3166_2.py --json_filename=iso3166_2.json --output_folder=iso3166_2 --verbose

--alpha2_codes: list of 1 or more 2 letter alpha-2 country codes (if not specified then all country codes will be used).
--json_filename: output filename for exported JSONs.
--output_folder: output folder to store JSONs.
--verbose: if set to 1 then the progress of the ISO 3166-2 data export will be output.

To download all of the latest ISO 3166-2 subdivision data for Germany, Portugal and Spain (the data will be exported to a JSON called iso3166_2-DE,ES,PT.json):

python3 get_iso3166_2.py --alpha2_codes=DE,PT,ES --json_filename=iso3166_2.json 

Issues or Contributing

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

Contact

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

References

[1]: https://en.wikipedia.org/wiki/ISO_3166
[2]: https://en.wikipedia.org/wiki/ISO_3166-2

Support

Back to top