Welcome to ISO 3166-2’s documentation 🌎!

iso3166_2 pytest License: MIT codecov https://upload.wikimedia.org/wikipedia/commons/3/3d/Flag-map_of_the_world_%282017%29.png

Introduction

iso3166-2 is a lightweight custom-built Python package, and accompanying RESTfulAPI, that can be used to access all of the world’s ISO 3166-2 subdivision data. Here, subdivision can be used interchangeably with regions/states/provinces etc. 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. The ISO 3166-2 was first published in 1998 and as of December 2025 there are 5,046 codes defined in it.

The ISO 3166-2 standard is part of the broader ISO 3166 family, maintained by the International Organization for Standardization (ISO). It provides codes for the names of the principal subdivisions (e.g., provinces or states) of all countries that have codes defined in ISO 3166-1. These codes are widely used in geopolitics, logistics, statistics, and software systems for consistent country and region identification.

There are 7 main data attributes available for each subdivision/subdivision code within the iso3166-2 software:

  • Name - subdivision name, as it is commonly known in English

  • Local/other name - subdivision name in local language or any alternative names its known by

  • Latitude/Longitude - subdivision coordinates

  • Flag - subdivision flag from the custom-built iso3166-flags repo

  • Parent Code - subdivision’s parent code

  • Type - subdivision type, e.g. region, state, canton, parish etc

  • History - historical updates/changes to the subdivision and its data, from the custom-built iso3166-updates repo

Bespoke Features

There are three main attributes supported by the software that make it stand out and add a significant amount of value and data per subdivision, in comparison to some the other iso3166-2 datasets, these are the local/other name, flag and history attributes.

Local/other name

The localOtherName attribute is built from a custom dataset of local language variants and alternative names/nicknames for the over 5000 subdivisions. In total there are >3700 local/other names for the >5000 subdivisions. Primarily the attribute contains local language translations for the subdivisions related to the subdivision, but many also include nicknames and other variants that the subdivision may be known by, either locally or globally.

For each local/other name, the ISO 639 3 letter language code is used to identify the language of the name. Some translations do not have available ISO 639 codes, therefore the Glottolog or other databases (e.g IETF) language codes are used. Some example local/other name entries are:

  • Sindh (Pakistan PK-SD) - “سِنْدھ (urd), Sindh (eng), SD (eng), Mehran/Gateway (eng), Bab-ul-Islam/Gateway of Islam (eng)”

  • Central Singapore (Singapore SG-01) - “Pusat Singapura (msa), 新加坡中部 (zho), மத்திய சிங்கப்பூர் (tam)”

  • Bobonaro (East Timor TL-BO) - “Bobonaru (tet), Buburnaru (tet), Tall eucalypt (eng)”

  • Wyoming (USA US-WY) - “Equality State (eng), Cowboy State (eng), Big Wyoming (eng)”

The full dataset of local/other names is available in the repo here local_other_names.csv.

Flags

The other equally important and bespoke/unique attribute that the software package supports is the flag attribute, which is a link to the subdivision’s flag on the iso3166-flags repo. This is another custom-built repository, (alongside iso3166-2 and iso3166-updates) that stores a rich and comprehensive dataset of over 2800 official individual subdivision flags, alongside ~250 ISO 3166-1 country/territory flags.

The flags repo uses the iso3166-2 software to get the full list of ISO 3166-2 subdivision codes which is kept up-to-date and accurate via the iso3166-updates software.

❤️ iso3166-2 🤝 iso3166-updates 🤝 iso3166-flags ❤️

History

The history attribute has any applicable historical updates/changes to the individual subdivisions. The data source for this is another custom-built software package previously mentioned called iso3166-updates. This package keeps track of all the published changes that the ISO make to the ISO 3166 standard which include addition of new subdivisions, deletion of existing subdivisions or amendments to existing subdivisions. Thus iso3166-updates helps ensure that the data in the iso3166-2 package is also kept up-to-date and accurate. If any updates are found for the subdivision a short description of the change, it’s publication date as well as its source will be included.

❤️ iso3166-2 🤝 iso3166-updates ❤️

Upcoming Features

There are several new features and attributes that are currently being worked on and will be added to the software package in the near future. These include: * Demographics - addition of key demographic data attributes such as area, population, population density etc for each subdivision * Enhanced Geo Data - addition of more detailed geo data attributes such as bounding box and geojson (these attributes are exportable via the custom scripts but yet to be implemented into the dataset)

Version

The iso3166-2 software is currently at version v1.8.2.

Last Updated

The ISO 3166-2 data was last updated on June 2025. A log of the latest ISO 3166-2 updates can be seen in the UPDATES.md file in the repository.

License

iso3166-2 is distributed under the MIT license.

Contributing

If you have found a bug or an issue in the software or API then please raise an issue on the repository’s Issues tab.

If you would like to contribute any functional/feature changes to the software, please make a pull request on the repository.

Any other queries or issues, please contact me via email: amckenna41@qub.ac.uk.

Credits

The Python software and accompanying API are solely developed and maintained by me 😁.

Note

A demo of the software and accompanying API is available here!

A Medium article about the iso3166-2 software and API is available here!

Contents

Back to top ↑