Usage ===== .. _installation: Installation ------------ To use **iso3166-updates**, firstly install via ``pip``: .. code-block:: console 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. .. code-block:: python 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): .. code-block:: python 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: .. code-block:: python 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): .. code-block:: python 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: .. code-block:: python 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: .. code-block:: python 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: .. code-block:: python 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: .. code-block:: python 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: .. code-block:: python 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: .. code-block:: python 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: .. code-block:: python 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: .. code-block:: python 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. .. code-block:: python 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. .. code-block:: python 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. .. code-block:: python 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. .. code-block:: python 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 :class:`Map` dict keyed by ISO 3166-1 alpha-2 code, accessible via dot notation. .. code-block:: python 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 `_.