Welcome to ISO 3166 Update’s documentation 🌎!
iso3166-updates is a software and accompanying API that consists of a series of scripts that check for any updates/changes to the ISO 3166 country codes and subdivision naming conventions, as per the ISO 3166 newsletter (https://www.iso.org/iso-3166-country-codes.html) and Online Browsing Platform (OBP) (https://www.iso.org/obp/ui).
The ISO 3166 standard by the ISO (International Organization for Standardisation) defines codes for the names of countries, dependent territories, special areas of geographical interest, consolidated into the ISO 3166-1 standard, and their principal subdivisions (e.g., provinces, states, departments, regions), which comprise the ISO 3166-2 standard. The ISO 3166-1 was first published in 1974 and currently comprises 249 countries, 193 of which are sovereign states that are members of the United Nations 🇺🇳. The ISO 3166-2 was first published in 1998 and as of November 2023 there are 5,039 codes defined in it.
The ISO is a very dynamic organisation and regularly change, update and or remove entries within its library of standards, including the ISO 3166. Additions, changes and deletions to country/territorial codes occur less often in the ISO 3166-1, but changes are more frequent for the ISO 3166-2 codes due to there being thousands more entries, thus it can be difficult to keep up with and track these changes. These changes can occur for a variety of geopolitical and administrative reasons. Previously these changes were communicated via newsletters; but as of July 2013 these changes are now communicated via their online catalogue/Online Browsing Platform (OBP), or via a database, which usually costs money to subscribe to (>$300). Usually these updates are conveyed at the end of the year, with amendments and updates occasionally published at various times throughout the year.
This software and accompanying API make it extremely easy to check for any new or historic updates to a country or set of country’s ISO 3166-2 codes for free; with an easy-to-use interface and Python package and API, ensuring that you get the most up-to-date and accurate ISO 3166-2 codes and naming conventions.
Each ISO 3166 update entry has 4 main data attributes:
Edition/Newsletter: name and or edition of newsletter that the ISO 3166 change/update was communicated in (pre 2013), or the link to the country’s ISO Online Browsing Platform (OBP) page.
Date Issued: date that the change was communicated.
Code/Subdivision change: overall summary of change/update made.
Description of Change: more in-depth info about the change/update that was made, including any remarks listed on the official ISO page.
Last Updated
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.
License
iso3166-updates is distributed under the MIT license.
Note
A demo of the software and accompanying API is available here!
Contents
- Usage
- Installation
- Get all ISO 3166 updates for all countries and years
- Get all ISO 3166 updates for a country using its ISO 3166-1 alpha code (alpha-2, alpha-3, numeric)
- Get all ISO 3166 updates from a year or list of years
- Get all ISO 3166 updates from a year range
- Get all ISO 3166 updates greater than or less than a year
- Get all ISO 3166 updates from the previous number of months or month range
- API
- Get all ISO 3166 updates for all countries and years
- Get all ISO 3166 updates for a country using its ISO 3166-1 alpha code (alpha-2, alpha-3, numeric)
- Get all ISO 3166 updates for a country using its country name
- Get all ISO 3166 updates from a year or list of years
- Get all ISO 3166 updates from a year range
- Get all ISO 3166 updates greater than or less than a year
- Get all ISO 3166 updates for a country and year, list of years, year range or greater than or less than a year
- Get all ISO 3166 updates for all countries from the previous months or month range
- Get all ISO 3166 updates for a country from the previous months or month range
- Contributing