ISO3166-2

Custom-built Python wrapper for RestCountries (https://restcountries.com/) API which includes an abundance of information about all ISO3166 countries. But this package also includes information about all countrys' ISO3166-2 subdivision codes & names, which is absent from RestCountries. Available via a Python software package; a demo is available [colab][here].

Table of Contents

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

Introduction

iso3166-2 is a custom-built Python wrapper for RestCountries (https://restcountries.com/) API which includes an abundance of information about all ISO3166 countries. But this package also includes information about all countrys' ISO3166-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]. This repo focuses on the ISO3166-2 standard.

The ISO 3166-2 defines codes for identifying the principal subdivisions (e.g., provinces, states, municipality etc) of all countries coded in 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.

Latest Updates

An important thing to note about the ISO3166-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 subdivision. Therefore, it's important that this library and its jsons have the most up to date data. To achieve this, the iso3166-updates repo was created.

The iso3166-updates repo is another software pacakge and accompanying API that pulls the latest updates and changes for any and all countries in the ISO3166. The API is called every few months to check for any updates, which will then be manually incorporated into this repo. Similarly, the getISO3166_2.py script is called regularly to check for any updates for all country data using the restcountries API.

Installaion

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

Requirements

• python >= 3.7
• requests >= 2.28.1
• iso3166 >= 2.1.1

Usage

Download all ISO3166-2 subdivision data using getISO3166_2.py script, export to two JSONs:

python3 getISO3166_2.py --json_filename=iso3166_2.json --output_folder=iso3166_2

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_iso3166_2 = iso.country["FJ"]

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

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 

Attributes

You can check the ATTRIBUTES.md file to get a description for each attribute/field in the json exports.

Issues or Contributing

Any issues, errors or bugs can be raised via the Issues tab in the repository. Due to the nature of the ISO consistently updating the ISO3166-2 codes/names every year the data in the JSON's may slightly lag behind these changes. My iso3166-updates repo was created to check for these updates periodically and implement them in the relevant repo's.

Contact

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

References

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

Support

Back to top