Usage

Installation

To use iso3166-updates, firstly install via pip:

pip install iso3166-updates

Get all ISO 3166 updates for all countries and years

Return all the latest and historic ISO 3166 updates data for all available countries and publication years. You will need to firstly create an instance of the Updates class and then access the all attribute object instance. You can then access an individual country’s ISO 3166 updates data by passing in the sought ISO 3166-1 2 letter alpha-2, 3 letter alpha-3 or numeric country code.

from iso3166_updates import *

#create instance of Updates class
iso = Updates()

#get all data from 'all' attribute of class
all_updates_data = iso.all

all_updates_data["AD"] #all updates data for Andorra
all_updates_data["DZ"] #all updates data for Algeria
all_updates_data["TUV"] #all updates data for Tuvalu
all_updates_data["YEM"] #all updates data for Yemen
all_updates_data["704"] #all updates data for Vietnam

Get all ISO 3166 updates for a country using its ISO 3166-1 alpha code (alpha-2, alpha-3, numeric)

Return all the latest and historic ISO 3166 updates data for 1 or more countries, using the country’s ISO 3166-1 alpha-2, alpha-3 or numeric codes. You firstly need to create an instance of the Updates class and then pass in the sought ISO 3166-1 codes. You can also return multiple country’s data by passing in a comma separated list of country codes.

For example, Egypt (EG, EGY, 818), Jordan (JO, JOR, 400) and Bosnia & Herz (BA, BIH, 070):

from iso3166_updates import *

#create instance of Updates class
iso = Updates()

eg_updates = iso["EG"] #EGY, 818
jo_updates = iso["JOR"] #JO, 400
ba_updates = iso["070"] #BA, BIH

#all of the above updates can be returned to the same variable
eg_jo_ba_updates = iso["EG, JOR, 070"]

You can also pass in the sought country code or country codes to the object instantiation using the country_code input parameter, if only their updates are required from the dataset. This allows for memory to be saved and for all updates data to not be unnecessarily imported on object instantiation.

For example, if only Sao Tome & Principe’s (ST, STP, 678) updates data is needed:

from iso3166_updates import *

#create instance of Updates class
iso_st = Updates(country_code="ST")

Get all ISO 3166 updates from a year or list of years

Return all the ISO 3166 updates data from a specific year or list of years, using the year() function within an object instance of the Updates class, passing in the required years as parameters.

For example, 2009 and (2001,2004,2019):

from iso3166_updates import *

#create instance of Updates class
iso = Updates()

#get all updates for 2009
iso.year("2009")

#get all updates for 2001, 2004, 2019
iso.year("2001, 2004, 2019")

Get all ISO 3166 updates from a year range

Return all the ISO 3166 updates data from a specific year range, using the year() function within an object instance of the Updates class, passing in the required year range as parameter.

For example, 2010-2015 and 2001-2005:

from iso3166_updates import *

#create instance of Updates class
iso = Updates()

#get all updates between 2010-2015
iso.year("2010-2015")

#get all updates between 2001-2005
iso.year("2001-2005")

Get all ISO 3166 updates greater than or less than a year

Return all the ISO 3166 updates data that are greater than or less than a specific year, using the year() function within an object instance of the Updates class, passing in the required year as parameters.

For example, <2020 and >2022:

from iso3166_updates import *

#create instance of Updates class
iso = Updates()

#get all updates with year less than 2020
iso.year("<2020")

#get all updates with year greater than or equal to 2022
iso.year(">2022")

Get all ISO 3166 updates excluding a year or list of years

Return all the ISO 3166 updates data but excluding data with a specified publication year or list of years, using the year() function within an object instance of the Updates class, passing in the required years as parameters.

For example, <>2004 and <>2019:

from iso3166_updates import *

#create instance of Updates class
iso = Updates()

#get all updates, excluding publication year 2004
iso.year("<>2004")

#get all updates, excluding publication year 2019
iso.year("<>2019")

#get all updates, excluding both publication years 2004 and 2019
iso.year("<>>2004,2019")

Get all ISO 3166 updates from a specific date range

Return all the ISO 3166 updates data published within a specified date range, inclusive, using the date_range() function within an object instance of the Updates class, passing in the required date range range as parameter. You can also sort the output by publication date via the sort_by_date parameter. The accepted values are dateDesc and dateAsc which will sort the outputs date descending and ascending, respectively.

For example, 2012-04-15 to 2013-11-11:

from iso3166_updates import *

#create instance of Updates class
iso = Updates()

#get all updates within specified date range, inclusive
iso.date_range("2012-04-15,2013-11-11")

#get all updates from specified date range, inclusive, sort by Date Issued rather than default Country Code, can be sorted descending or ascending
iso.date_range("12/04/2015,07/05/2010", sort_by_date="dateDesc")

#get all updates from specified date, inclusive
iso.date_range("2012-04-15")

Search for all ISO 3166 updates that have specific keywords

Return all the ISO 3166 updates data who’s changes/description of change attributes feature the inputted search terms, using the search() function within an object instance of the Updates class, passing in the required search terms as parameters. The function also accepts the likeness_score parameter which sets a % of likeness that the input search term can be to the matching updates, by default a likeness of 100 (an exact match) is used. If a date is explicitly input to the search function, the Date Issued column will additionally be added to the search space. The outputs from the search are ordered by match_score, highest match first. The match score can be stripped from the output by setting include_match_score=False, which causes results to be ordered alphabetically by country code instead.

For example, Paris, RU-PSK or addition/deletion:

from iso3166_updates import *

#create instance of Updates class
iso = Updates()

#search for any update objects that have Paris in them
iso.search("Paris")

#search for any update objects that have RU-PSK in them
iso.search("RU-PSK")

#search for any update objects that have addition or deletion in them, reduce % likeness score to 80
iso.search("addition, deletion", likeness_score=80)

#search for any update objects that have the date 2023-11-23, strip the % match score from output
iso.search("2023-11-23", include_match_score=False)

Get a high-level summary of the dataset

Return a concise dict of dataset statistics using the stats() method — useful for data quality checks, dashboard widgets, or a quick sanity check after loading a custom dataset:

from iso3166_updates import *

iso = Updates()
iso.stats()
# {
#   'total_updates': 911,
#   'total_countries': 250,
#   'year_range': [1996, 2025],
#   'most_updated_country': 'FR',
#   'most_common_change_type': 'addition',
#   'last_updated': '2025-07-22'
# }

Add custom ISO 3166 updates

Add or delete a custom change/update to an existing country in the main iso3166-updates.json object. Custom updates can be used for in-house/bespoke applications that are using the iso3166-updates software but require additional custom changes/updates to be included. When adding a new update, the “Change” and “Date Issued” attributes are required with the “Description of Change” and “Source” attributes being optional. If the input custom change/update already exists then an error will be raised, otherwise it will be appended to the main object.

If the added change/update is required to be deleted from the object, then you can call the same function with the “Change” and “Date Issued” parameters/attributes of the added change/update, but also setting the ‘delete’ parameter to 1/True. You can also uninstall and reinstall to reset the main object.

To avoid writing over the main existing updates file you can export to a separate object via the save_new and save_new_filename parameters.

Note that this is a destructive yet temporary functionality. Adding a new custom change/update will make the dataset out of sync with the official ISO 3166 Updates data, therefore it is the user’s responsibility to keep track of any custom changes/updates and delete them when necessary.

For example, adding custom Kenyan and Belfast updates:

from iso3166_updates import *

#create instance of Updates class
iso = Updates()

#adding custom update object for Kenya
iso.custom_update(alpha_code="KE", change="New subdivision added", date_issued="2025-01-01", description_of_change="big ole description")

#adding custom update object for Belfast, save to new file
iso.custom_update("IE", change="Brand new Belfast subdivision", date_issued="2020-05-12", description_of_change="", source="https:...",
   save_new=1, save_new_filename="ie-custom-update.json")

If you need to remove the custom updates you can set the delete parameter in the same function to True, e.g custom Kenyan and Belfast updates:

from iso3166_updates import *

#create instance of Updates class
iso = Updates()

#deleting custom update object for Kenya
iso.custom_update(alpha_code="KE", change="New subdivision added", date_issued="2025-01-01", delete=1)

#deleting custom update object for Belfast
iso.custom_update("IE", change="Brand new Belfast subdivision", date_issued="2020-05-12", delete=1)

Get all ISO 3166 updates using a custom updates object

Return all the latest and historic ISO 3166 updates data for all available countries and publication years, using a custom updates object specified by the updates_filepath class parameter. The custom object should be in the same format and structure as the original updates object. You can firstly create an instance of the Updates class, passing in the desired filepath and then access the all attribute object instance. You can then access an individual country’s ISO 3166 updates data by passing in the sought ISO 3166-1 2 letter alpha-2, 3 letter alpha-3 or numeric country code.

from iso3166_updates import *

#create instance of Updates class
iso = Updates(custom_updates_filepath="custom_filepath.json")

#get all data from 'all' attribute of class
all_updates_data = iso.all

all_updates_data["AD"] #all updates data for Andorra
all_updates_data["DZ"] #all updates data for Algeria
all_updates_data["TUV"] #all updates data for Tuvalu
all_updates_data["YEM"] #all updates data for Yemen
all_updates_data["704"] #all updates data for Vietnam

Get the total number of ISO 3166 updates

Return the total number of individual ISO 3166 updates objects within the imported JSON of the class, via the in-built len() function.

from iso3166_updates import *

#create instance of Updates class
iso = Updates()

#get total number of updates object via len()
len(iso)

Check for the latest ISO 3166 updates from repository

Check for the latest updates data from the repository in comparison to the current object in the software. This is to ensure that the version of the software you are using is up-to-date with the latest data. The function will return what changes, if any, need to be incorporated into your current object. If there are any changes, it’s recommended to upgrade to the latest version of the software.

from iso3166_updates import *

#create instance of Updates class
iso = Updates()

#compares local dataset with the latest version in the repository
iso.check_for_updates()

Get the most recent publication date in the dataset

Return the most recently published Date Issued value across the entire dataset as a YYYY-MM-DD string, using the last_updated property on an Updates class instance. This is useful for auto-populating documentation, dashboards, or any code that needs to know when the dataset was last updated without manually maintaining the date.

from iso3166_updates import *

#create instance of Updates class
iso = Updates()

#get most recent Date Issued across all updates (YYYY-MM-DD)
iso.last_updated

Filter updates by change type

Filter the dataset by the structural type of change using the change_type() method on an Updates class instance. The method classifies each update via keyword matching on the Change and Description of Change fields into one of four categories: addition, deletion, correction, or amendment. A comma-separated list of multiple types is also accepted. The result is a Map dict keyed by ISO 3166-1 alpha-2 code, accessible via dot notation.

from iso3166_updates import *

#create instance of Updates class
iso = Updates()

#get all updates where new subdivisions or codes were added
iso.change_type("addition")

#get all updates where existing subdivisions or codes were removed
iso.change_type("deletion")

#get all updates that represent spelling or error corrections
iso.change_type("correction")

#get all updates that represent renames, merges, or re-categorisations
iso.change_type("amendment")

#combine multiple types in a single call
iso.change_type("correction,amendment")

Note

A demo of the software and API is available here.