iso3166-updates

Automated scripts that check for any updates/changes to the ISO3166-1 and ISO3166-2 country codes and naming conventions, as per the ISO3166 newsletter (https://www.iso.org/iso-3166-country-codes.html) and Online Browsing Platform (OBP) (https://www.iso.org/obp/ui). Available via a Python software package and API; a demo of both is available here.

Table of Contents

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

Introduction

iso3166-updates is a repo that consists of a series of scripts that check for any updates/changes to the ISO3166-1 and ISO3166-2 country codes and naming conventions, as per the ISO3166 newsletter (https://www.iso.org/iso-3166-country-codes.html). The ISO3166 standard by the ISO defines codes for the names of countries, dependent territories, special areas of geographical interest, consolidated into the ISO3166-1 standard [1], and their principal subdivisions (e.g., provinces, states, departments, regions), which compromise the ISO3166-2 standard [2].

Problem Statement

The ISO is a very dynamic organisation and regularly change/update/remove entries within its library of standards, this includes the ISO3166. Additions/changes/deletions to country/territorial codes in the ISO3166-1 are a lot less frequent than for the ISO3166-2 codes due to there being thousands more entries, thus it can be difficult to keep up with any changes to these codes. These changes are usually communicated via Newsletters on the ISO platform or Online Browsing Platform or via a database which usually costs money to subscribe to [3]. This software and accompanying API makes it extremely easy to check for any new or historic updates to a country or set of countrys' ISO3166-2 codes for free with an easy to use interface and Python package. This software is for anyone working on projects working directly with country codes and who want up-to-date and accurate ISO3166-2 codes and naming conventions.

API

An API is available that can be used to extract any applicable updates for a country via a URL. The API is in alpha stage so is just available via a Google Function at URL:

https://us-central1-iso3166-updates.cloudfunctions.net/iso3166-updates

The API documentation and usage with all useful commands and inputs to the API is available on the README of the iso3166-updates-api folder. The API was built using GCP utilsing a Cloud Function backed by an API Gateway that can be called via a http trigger at the above url, the Function calls GCP Storage to access the back-end JSON with all ISO3166 updates. This JSON is updated regularly using a CRON job that is called every X months.

Requirements

• python >= 3.7
• pandas >= 1.4.3
• requests >= 2.28.1
• beautifulsoup4 >= 4.11.1
• iso3166 >= 2.1.1

Installation

Install the latest version of iso3166-updates using pip:

pip3 install iso3166-updates

Installation from source:

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

Usage

Import package

import iso3166_updates as iso3166_updates

Get all listed changes/updates for Andorra from wiki (https://en.wikipedia.org/wiki/ISO_3166-2:AD)

iso3166_updates.get_updates("AD")

Get all listed changes/updates for BA, DE, FR, HU, PY

iso3166_updates.get_updates(["BA","DE","FR","HU","PY"])

Get any listed changes/updates for HU, IT, JA, KE from wiki, in the year 2018

iso3166_updates.get_updates("HU, IT, JA, KE", year="2018")

Get any listed changes/updates for Ireland from wiki (https://en.wikipedia.org/wiki/ISO_3166-2:IE), between years of 2012 and 2021

iso3166_updates.get_updates("IE", year="2012-2021")

Get any listed changes/updates for Tanzania from wiki (https://en.wikipedia.org/wiki/ISO_3166-2:TZ), with updates years > 2015

iso3166_updates.get_updates("TA", year=">2015")

Get any listed changes/updates for Yemen from wiki (https://en.wikipedia.org/wiki/ISO_3166-2:YE), with updates years < 2010

iso3166_updates.get_updates("YE", year=">2010")

The output to the above functions for the updates/changes to a ISO3166-2 country returns 4 columns: Edition/Newsletter, Date Issued, Description of change in newsletter and Code/Subdivision change. E.g the output csv format for AD (Andorra) is:

Issues

Any issues, errors or bugs 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 on the [Issues][Issues] tab.

References

[1]: https://en.wikipedia.org/wiki/ISO_3166-1
[2]: https://en.wikipedia.org/wiki/ISO_3166-2
[3]: ISO Country Codes Collection: https://www.iso.org/publication/PUB500001
[4]: https://github.com/lipis/flag-icons

Support

Back to top