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. This score can be excluded from the output
by setting the exclude_match_score to 1, meaning the outputs will be ordered alphabetically by country code.
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, exclude the % match score from output
iso.search("2023-11-23", exclude_match_score=1)
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.
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
iso.custom_update("IE", change="Brand new Belfast subdivision", date_issued="2020-05-12", description_of_change="", source="https:...")
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()
Note
A demo of the software and API is available here.