search

amckenna41 / iso3166-2

A lightweight Python package, and accompanying API, that can be used to access all of the world's most up-to-date and accurate ISO 3166-2 subdivision data, including: name, local name, code, parent code, type, latitude/longitude, flag and more.
https://iso3166-2-api-amckenna41.vercel.app/
MIT License
8 stars 0 forks source link
api countries geographic-data geonames iso3166 iso3166-2 iso3166-flag-icons iso3166-updates json python regions world-data world-flags

readme

ISO 3166-2 🌎

iso3166_2 pytest CircleCI PythonV Platforms Documentation Status License: MIT Issues

globe

iso3166-2 is a lightweight custom-built Python package, 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. The software uses another custom-built Python package called iso3166-updates to ensure all the subdivision data is accurate, reliable and up-to-date.

Table of Contents

Introduction

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, municipalities 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." For some countries, codes are defined for more than one level of subdivisions.

Currently, this package and accompanying API support subdivision data from 250 officially assigned code elements within the ISO 3166-1, with 200 of these countries having recognised subdivisions (50 entires have 0 subdivisions), totalling 5,039 subdivisions across the whole dataset. Transitional reservations are not included and only 4 of the exceptional reservations, that have now been officially assigned, are included: AX (Aland Islands), GG (Guernsey), IM (Isle of Man) and JE (Jersey) [3]. The ISO 3166-2 was first published in 1998 and as of November 2023 there are 5,039 codes defined in it [2].

The full list of subdivision data attributes supported are:

The above 7 attributes were chosen as they are the most relevant and useful pieces of data for each subdivision. Other attributes are available in scattered data sources such as area, population, regional name translations, geonames ID, FIPS code etc but these are less relevant than the ones included, unless someone really desires the population of the Bhutan region of Bumthang (17,820 btw). It was an aim during development to make the package as lightweight as possible, therefore for example if the 5 aforementioned attributes were included for the existing 5,039 codes, this would significantly increase the size of the dataset from ~1.7MB to ~2.8MB.

Motivation

The primary motivation for building this software was for use in my iso3166-flag-icons project. When building the dataset of flags, I found that some existing projects/softwares were inaccurate, outdated and or not maintained. As mentioned the ISO 3166-2 is a dynamic and ever-changing standard therefore it can be difficult to maintain and keep up-to-date; although in the case for this software, that problem is largely alleviated thanks to the custom-built iso3166-updates package (see next section).

Furthermore, there are existing toolkits and datasets that offer a rich collection of regional attributes data, geonames for example. Although, many of these datasets are very large in size and difficult to parse, with an abundance of unessential data attributes. Thus the aim during development was to build a lightweight ISO 3166-2 dataset with the most sought data attributes that can be easily packaged into a Python package.

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 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 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 March 2024. A log of the latest ISO 3166 updates can be seen in the UPDATES.md file.

API

The main API endpoint is:

https://iso3166-2-api.vercel.app/api

The other endpoints available in the API are:

Six paths/endpoints are available in the API - /api/all, /api/alpha, /api/country_name, /api/subdivision, /api/name and /api/list_subdivisions.

The API documentation and usage with all useful commands and examples to the API is available on the API.md file. A demo of the software and API is available here.

Requirements

Installation

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

pip install iso3166-2 --upgrade

Usage

The main JSON iso3166-2.json contains each country's ISO 3166-2 subdivision data and attributes. The data can be accessed after creating an instance of the ISO3166_2 class, with the instance being subscriptable such that data can be accessed via their ISO 3166-1 alpha-2, alpha-3 or numeric country codes.

Get all ISO 3166-2 data for all countries:

from iso3166_2 import *

#create instance of ISO3166_2 class
iso = ISO3166_2()

#get all subdivision data using all attribute
iso.all

Get all subdivision data for specific countries:

from iso3166_2 import *

#create instance of ISO3166_2 class
iso = ISO3166_2()

#access all country's subdivision data
canada_iso3166_2 = iso["CA"]
denmark_iso3166_2 = iso["DK"]
estonia_iso3166_2 = iso["EST"]
peru_iso3166_2 = iso["PER"]
fiji_haiti_guyana_iso3166_2 = iso["FJ, HTI, 328"]

Get a specific subdivision's info:

from iso3166_2 import *

#create instance of ISO3166_2 class
iso = ISO3166_2()

iso["CA"]['CA-AB'] #Alberta subdivision
iso["DK"]['DK-81'] #Nordjylland subdivision
iso["EST"]['EE-899'] #Viljandi subdivision
iso["FJI"]['FJ-03'] #Cakaudrove subdivision 
iso["604"]['PE-AMA'] #Amarumayu subdivision

Get individual attribute values per subdivision:

from iso3166_2 import *

#create instance of ISO3166_2 class
iso = ISO3166_2()

iso["CA"]['CA-AB'].latLng #Alberta subdivision latitude/longitude
iso["DK"]['DK-81'].flag #Nordjylland subdivision flag URL
iso["EST"]['EE-899'].name #Viljandi subdivision name
iso["FJI"]['FJ-03'].type #Cakaudrove subdivision type
iso["604"]['PE-AMA'].parentCode #Amarumayu subdivision

Searching for a specific subdivision via its subdivision name attribute:

from iso3166_2 import *

'''
The search functionality will search over all subdivisions in the object, 
returning either a subdivision with the exact match or subdivisions whose names 
approximately match the sought input name according to the likeness input parameter
'''

#create instance of ISO3166_2 class
iso = ISO3166_2()

#searching for the Monaghan county in Ireland (IE-MN) - returning exact matching subdivision
iso.search("Monaghan")

#searching for any subdivisions that have "Southern" in their name, using a likeness score of 0.8
iso.search("Southern", likeness=0.8)

#searching for state of Texas and French Department Meuse - both subdivision objects will be returned
iso.search("Texas, Meuse")

Adding a custom subdivision to the iso3166-2 object:

from iso3166_2 import *

'''
The context for this functionality is similar to that of the user-assigned 
code elements of the ISO 3166-1 standard. Custom subdivisions and subdivision 
codes can be used for in-house/bespoke applications that are using the 
iso3166-2 software but require additional custom subdivisions to be represented
'''

#adding custom Belfast province to Ireland
iso.custom_subdivision("IE", "IE-BF", name="Belfast", local_name="Béal Feirste", type_="province", lat_lng=[54.596, -5.931], parent_code=None, flag=None)

#adding custom Republic of Molossia state to United States 
iso.custom_subdivision("US", "US-ML", name="Republic of Molossia", local_name="", type_="State", lat_lng=[39.236, -119.588], parent_code=None, flag="https://upload.wikimedia.org/wikipedia/commons/c/c3/Flag_of_the_Republic_of_Molossia.svg")

#deleting above custom subdivisions from object
iso.custom_subdivision("IE", "IE-BF", delete=1)
iso.custom_subdivision("US", "US-ML", delete=1)

Documentation

Documentation for installation and usage of the software and API is available on the readthedocs platform:

https://iso3166-2.readthedocs.io/en/latest/

ISO 3166-2 Scripts

Please visit the README of the iso3166_2_scripts folder for more in depth info about the usage and requirements of the above two scripts vital to the iso3166-2 software.

Directories

Issues or Contributing

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.

Also, due to the large amount of data and attributes in the dataset, please raise an Issue if you spot any missing or erroneous data. When raising this Issue please include the current subdivision object attribute values as well as the corrected/new version of them in an easy-to-read format.

Contact

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

Other ISO 3166 repositories

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

References

[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/#

Support

Buy Me A Coffee

Back to top