| Name | iso3166-2 JSON |
| Version |
1.7.0
JSON |
| download |
| home_page | https://iso3166-2-api.vercel.app/api |
| Summary | A lightweight Python package, and accompanying API, used to access all of the world's most up-to-date and accurate ISO 3166-2 subdivision data, including: name, local/other name, code, parent code, type, latitude/longitude, flag and history. |
| upload_time | 2025-07-18 11:49:56 |
| maintainer | AJ McKenna |
| docs_url | None |
| author | AJ McKenna |
| requires_python | <4.0,>=3.9 |
| license | MIT |
| keywords |
iso
iso3166
beautifulsoup
python
pypi
countries
country codes
iso3166-2
iso3166-1
alpha-2
iso3166-updates
subdivisions
regions
dataset
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<a name="TOP"></a>
# iso 3166-2 🌎
[](https://pypi.org/project/iso3166-2/)
[](https://github.com/amckenna41/iso3166-2/actions?query=workflowBuilding%20and%20Testing)
<!-- [](https://dl.circleci.com/status-badge/redirect/gh/amckenna41/iso3166-2/tree/main) -->
[](https://pypi.org/project/iso3166-2/)
[](https://pypi.org/project/iso3166-2/)
[](https://iso3166-2.readthedocs.io/en/latest/?badge=latest)
[](https://opensource.org/licenses/MIT)
[](https://github.com/amckenna41/iso3166-2/issues)
<!-- [](https://github.com/amckenna41/iso3166-2) -->
<!-- [](https://github.com/iso3166-2) -->
<!-- [](https://codecov.io/gh/amckenna41/pySAR) -->
<div alt="images" style="justify-content: center; display:flex; margin-left=10px;">
<img src="https://upload.wikimedia.org/wikipedia/commons/3/3d/Flag-map_of_the_world_%282017%29.png" alt="globe" height="300" width="600"/>
<!-- <img src="https://upload.wikimedia.org/wikipedia/commons/e/e3/ISO_Logo_%28Red_square%29.svg" alt="iso" height="300" width="400"/> -->
</div>
> `iso3166-2` is a lightweight custom-built Python package, and accompanying RESTful API, that can be used to access all of the world's ISO 3166-2 subdivision data. A plethora of data attributes are available per country and subdivision including: name, local/other name, code, parent code, type, lat/longitude, flag & history. Currently, the package and API supports data from 250 countries/territories and >5000 subdivisions, according to the ISO 3166-1 & ISO 3166-2 standards, respectively. The software uses another custom-built Python package called [`iso3166-updates`](https://github.com/amckenna41/iso3166-updates/tree/main) to ensure all the subdivision data is accurate, reliable and up-to-date.
Quick Start 🏃
-------------
* A <b>demo</b> of the software and API is available [here][demo].
* The front-end <b>API</b> is available [here][api].
* The **documentation** for the software & API is available [here](https://iso3166-2.readthedocs.io/en/latest/).
* A <b>Medium</b> article that dives deeper into `iso3166-2` is available [here][medium].
<!-- * A <b>demo</b> of the script used to pull and export all the latest ISO 3166-2 data is available [here][demo_get_iso3166_2]. -->
Table of Contents
-----------------
- [Introduction](#introduction)
- [Bespoke Features](#bespoke-features)
- [Requirements](#requirements)
- [Installation](#installation)
- [Usage](#usage)
- [Documentation](#documentation)
- [Latest Updates](#latest-updates)
- [API](#api)
- [Directories](#directories)
- [Issues or Contributing](#issues-or-contributing)
- [Contact](#contact)
- [References](#references)
- [Support](#support)
## Introduction
The International Organisation for Standards defines codes for the names of countries, dependent territories, special areas of geographical interest, and their principal subdivisions [[1]](#references). The ISO 3166-2 defines codes for identifying the principal subdivisions (e.g. provinces, states, municipalities etc) of all countries coded in the ISO 3166-1. The official name of the standard is <i>"Codes for the representation of names of countries and their subdivisions – Part 2: Country subdivision code."</i> For some countries, codes are defined for more than one level of subdivisions.
Currently, this package and accompanying API support subdivision data from **250** officially assigned code elements within the ISO 3166-1, with **200** of these countries having recognised subdivisions (50 entires have 0 subdivisions), totalling **5,049** subdivisions across the whole dataset. Transitional reservations are not included and only 4 of the exceptional reservations, that have now been officially assigned, are included: AX (Aland Islands), GG (Guernsey), IM (Isle of Man) and JE (Jersey) [[3]](#references). The ISO 3166-2 was first published in 1998 and as of **November 2023** there are **5,049** codes defined in it [[2]](#references).
The full list of subdivision data attributes supported are:
* **Code** - ISO 3166-2 subdivision code
* **Name** - subdivision name
* **Local/other name** - subdivision name in local language or any alternative name/nickname it is commonly known by
* **Parent Code** - subdivision parent code
* **Type** - subdivision type, e.g. region, state, canton, parish etc
* **Latitude/Longitude** - subdivision coordinates
* **Flag** - subdivision flag from [`iso3166-flag-icons`](https://github.com/amckenna41/iso3166-flag-icons) repo; this is another ISO 3166 related custom-built dataset of over **3500** regional/subdivision flags
* **History** - historical updates/changes to the subdivision code and naming conventions, as per the custom-built [`iso3166-updates`](https://github.com/amckenna41/iso3166-updates) repo.
The above 8 attributes were chosen as they are the most relevant and useful pieces of data for each subdivision. Other attributes are available in scattered data sources such as area, population, regional name translations, geonames ID, FIPS code etc, but these were deemed less relevant than the ones included... unless someone really desires the population of the Bhutan region of Bumthang (17,820 btw). It was an aim during development to make the package as lightweight as possible, therefore for example if the 5 aforementioned attributes were included for the existing **5,049** codes, this would significantly increase the size of the dataset from **~3MB to ~4MB**.
### Motivation
The primary motivation for building this software was for use in my [`iso3166-flag-icons`](https://github.com/amckenna41/iso3166-flag-icons) project. When building the dataset of flags, I found that some existing projects/softwares were **inaccurate**, **outdated** and or **not maintained**. As mentioned, the ISO 3166-2 is a dynamic and ever-changing standard therefore it can be difficult to maintain and keep up-to-date; although in the case for this software, that problem is largely alleviated thanks to the custom-built [`iso3166-updates`](https://github.com/amckenna41/iso3166-updates) package (see below sections).
Furthermore, there are existing toolkits and datasets that offer a rich collection of regional attributes data, [geonames](https://www.geonames.org/) for example. Although, many of these datasets are very large in size and difficult to parse, with an abundance of unessential data attributes.
Thus the aim during development was to build a **structured, lightweight and up-to-date ISO 3166-2 dataset with the most sought data attributes that can be easily packaged into a Python package.**
<!-- ### Intended Audience
This package is particularly useful for developers and researchers building geographic information systems (GIS), global mapping tools, localization platforms, or projects involving geopolitical datasets. It’s designed to be easily integrated into Python applications with minimal overhead. -->
## Bespoke Features
There are two 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** and the **flag** attributes.
### Local/Other names
One of the most <b>important</b> and <b>bespoke</b> attributes that the software supports, that many others do not, is the **local/other name** attribute. This attribute is built from a custom dataset of local language variants and alternative names/nicknames for the <b>over 5000</b> subdivisions. In total there are <b>>3700</b> local/other names for the <b>>5000</b> subdivisions. Primarily the attribute contains local language translations for the subdivisions, but many also include <b>nicknames</b> and **alternative 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](https://glottolog.org/) or other databases (e.g [IETF](https://support.elucidat.com/hc/en-us/articles/6068623875217-IETF-language-tags)) 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`](https://github.com/amckenna41/iso3166-2/iso3166_2_resources/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-flag-icons`](https://github.com/amckenna41/iso3166-flag-icons) repo. This is another **custom-built** repository, (alongside [`iso3166-2`](https://github.com/amckenna41/iso3166-2) and [`iso3166-updates`](https://github.com/amckenna41/iso3166-updates)) that stores a rich and comprehensive dataset of over **3500** individual subdivision 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.
<div align="center">❤️ iso3166-2 🤝 iso3166-updates 🤝 iso3166-flag-icons ❤️</div>
## Requirements
* [python][python] >= 3.9
* [iso3166][iso3166] >= 2.1.1
* [natsort][natsort] >= 8.4.0
* [thefuzz][thefuzz] >= 0.22.1
* [requests][requests] >= 2.28.1
<!-- * [unidecode][unidecode] >= 1.3.8 -->
## Installation
Install the latest version of `iso3166-2` via [PyPi][PyPi] using pip:
```bash
pip install iso3166-2 --upgrade
```
## Usage
All of the country's subdivision data and attributes are encapsulated into an instance of the *Subdivisions* class via the JSON object **iso3166-2.json**, which contains each country's ISO 3166-2 subdivision data. The data can be accessed after creating an instance of the <i>Subdivisions</i> class, with the instance being subscriptable such that data can be accessed via their ISO 3166-1 alpha-2, alpha-3 or numeric country codes. There also exist a plethora of additional functionalities around the subdivisision data. Below are some usage examples for the software.
**Import and create instance of Subdivisions class:**
```python
from iso3166_2 import *
#create instance of Subdivisions class
iso = Subdivisions()
```
**Get all ISO 3166-2 data for all countries:**
```python
iso.all
```
**Get all subdivision data for a country, via their alpha-2, alpha-3 and numeric country codes:**
```python
canada_iso3166_2 = iso["CA"]
denmark_iso3166_2 = iso["DK"]
estonia_iso3166_2 = iso["EST"]
peru_iso3166_2 = iso["PER"]
fiji_haiti_iso3166_2 = iso["FJ, HT"]
fiji_haiti_guyana_iso3166_2 = iso["FJ, HTI, 328"]
```
**Get subdivision's data, via its subdivision code:**
```python
iso["CA"]['CA-AB'] #Alberta subdivision
iso["DK"]['DK-81'] #Nordjylland subdivision
iso["EST"]['EE-899'] #Viljandi subdivision
iso["FJI"]['FJ-03'] #Cakaudrove subdivision
iso["PE"]["PE-LAL"] #La Libertad subdivision
iso["604"]['PE-AMA'] #Amarumayu subdivision
```
**Get individual attribute values per subdivision:**
```python
iso["CA"]['CA-AB'].latLng #Alberta subdivision latitude/longitude
iso["DK"]['DK-81'].flag #Nordjylland subdivision flag URL
iso["PE"]['PE-LAL'].history #La Libertad subdivision updates history
iso["EST"]['EE-899'].name #Viljandi subdivision name
iso["FJI"]['FJ-03'].type #Cakaudrove subdivision type
iso["604"]['PE-AMA'].parentCode #Amarumayu subdivision
```
**Get subset of subdivision attributes for all countries:**
```python
'''
If only a subset of the available default attributes are required per
subdivision, include them via the 'filter_attributes' input parameter
when creating an instance of the class. All attributes not included
in this list will be excluded.
'''
from iso3166_2 import *
#create instance of Subdivisions class
iso = Subdivisions(filter_attributes="flag,parentCode,type")
```
**Searching for a specific subdivision via its subdivision name or local/other name attributes:**
```python
'''
The search functionality will search over all subdivisions in the object,
returning either a subdivision with the exact match or subdivisions whose names
approximately match the sought input name according to the likeness input parameter.
The likeness input parameter is a % similarity the input search terms have to be to
the subdivision names, with 100% being an exact match, vice versa. Reducing this
value will thus increase the search space and return more like results.
'''
from iso3166_2 import *
#create instance of Subdivisions class
iso = Subdivisions()
#searching for the Monaghan county in Ireland (IE-MN) - returning exact matching subdivision (likeness=100)
iso.search("Monaghan")
#searching for Castelo Branco district in Portugal (PT-05) - returning exact matching subdivision (likeness=100)
iso.search("Castelo Branco", likeness=100)
#searching for the Roche Caiman district in Seychelles (SC-25) - returning exact matching subdivision (likeness=100)
iso.search("Roche Caiman")
#searching for any subdivisions that have "Southern" in their name, using a likeness score of 80
iso.search("Southern", likeness_score=80)
#searching for any subdivisions that have "City" in their name or localOtherName attributes, using a likeness score of 40%
iso.search("City", likeness=40, local_other_name_search=True)
#searching for state of Texas and French Department Meuse - both subdivision objects will be returned, only including the subdivision type and name attributes
iso.search("Texas, Meuse", filter_attributes="name,type")
```
**Adding a custom subdivision to the iso3166-2 object:**
```python
'''
The context for this functionality is similar to that of the user-assigned
code elements of the ISO 3166-1 standard. Custom subdivisions and subdivision
codes can be used for in-house/bespoke applications that are using the
iso3166-2 software but require additional custom subdivisions to be represented.
You can also add custom attributes for the custom subdivision, e.g population,
area, gdp etc, via the custom_attribute parameter.
'''
from iso3166_2 import *
#create instance of Subdivisions class
iso = Subdivisions()
#adding custom Belfast province to Ireland
iso.custom_subdivision("IE", "IE-BF", name="Belfast", local_name="Béal Feirste", type_="province", lat_lng=[54.596, -5.931], parent_code=None, flag=None)
#adding custom Alaska province to Russia with additional population and area attribute values
iso.custom_subdivision("RU", "RU-ASK", name="Alaska Oblast", local_other_name="Аляска", type_="Republic", lat_lng=[63.588, 154.493], parent_code=None, flag=None,
custom_attributes={"population": "733,583", "gini": "0.43", "gdpPerCapita": "71,996"})
#adding custom Republic of Molossia state to United States
iso.custom_subdivision("US", "US-ML", name="Republic of Molossia", local_name="", type_="State", lat_lng=[39.236, -119.588], parent_code=None, flag="https://upload.wikimedia.org/wikipedia/commons/c/c3/Flag_of_the_Republic_of_Molossia.svg")
#deleting above custom subdivisions from object
iso.custom_subdivision("IE", "IE-BF", delete=1)
iso.custom_subdivision("US", "US-ML", delete=1)
iso.custom_subdivision("RU", "RU-ASK", delete=1)
```
**Check for the latest updates data from the repository:**
```python
'''
Compare the subdivision data in the current installed version of the
iso3166-2 software with the most up-to-date and accurate version on
the repository. If there are any difference between these objects,
they will be output.
'''
iso.check_for_updates()
```
**Get total number of subdivisions in object:**
```python
len(iso)
```
**Get size of dataset in MB:**
```python
iso.__sizeof__()
```
## Documentation
Documentation for installation and usage of the software and API is available on the readthedocs platform:
<b>https://iso3166-2.readthedocs.io/en/latest/</b>
## Latest Updates
An important thing to note about the ISO 3166-2 and its subdivision codes/names is that changes are made consistently to it, from a small subdivision name change to an addition/deletion of a whole subdivision. These changes can happen due for a variety of geopolitical and administrative reasons. Therefore, it's important that this library and its JSON have the most **up-to-date, accurate and reliable data**. To achieve this, the custom-built [`iso3166-updates`](https://github.com/amckenna41/iso3166-updates) repo was created!
The [`iso3166-updates`](https://github.com/amckenna41/iso3166-updates) repo is another open-source software package and accompanying RESTful API that pulls the latest updates and changes for any and all countries in the ISO 3166 from a variety of data sources including the ISO website itself. A script is called periodically to check for any updates/changes to the subdivisions, which are communicated via the ISO's Online Browsing Platform [[4]](#references), and will then be manually incorporated into this repo. Please visit the repository home page for more info about the purpose and process of the software and API - [`iso3166-updates`](https://github.com/amckenna41/iso3166-updates).
The list of ISO 3166 updates was last updated on <strong>November 2024</strong>. A log of the latest ISO 3166 updates can be seen in the [UPDATES.md][updates_md] file.
## API
The main API endpoint is:
> [https://iso3166-2-api.vercel.app/api](https://iso3166-2-api.vercel.app/api)
The other endpoints available in the API are:
* https://iso3166-2-api.vercel.app/api/all
* https://iso3166-2-api.vercel.app/api/alpha/<input_alpha>
* https://iso3166-2-api.vercel.app/api/country_name/<input_country_name>
* https://iso3166-2-api.vercel.app/api/subdivision/<input_subdivision>
* https://iso3166-2-api.vercel.app/api/search/<input_search_name>
* https://iso3166-2-api.vercel.app/api/list_subdivisions
Six paths/endpoints are available in the API - `/api/all`, `/api/alpha`, `/api/country_name`, `/api/subdivision`, `/api/search` and `/api/list_subdivisions`.
* `/api/all`: get all of the ISO 3166 subdivision data for all countries.
* `/api/alpha`: get all of the ISO 3166 subdivision data for 1 or more inputted ISO 3166-1 alpha-2, alpha-3 or numeric country codes, e.g. `/api/alpha/FR,DE,HU,ID,MA`, `/api/alpha/FRA,DEU,HUN,IDN,MAR` and `/api/alpha/428,504,638`. A comma separated list of multiple alpha codes can also be input. If an invalid country code is input then an error will be returned.
* `/api/country_name`: get all of the ISO 3166 subdivision data for 1 or more inputted ISO 3166-1 country names, as they are commonly known in English, e.g. `/api/country_name/France,Moldova,Benin`. A comma separated list of country names can also be input. A closeness function is utilised so the most approximate name from the input will be used e.g. Sweden will be returned if the input is `/api/country_name/Swede`. If no country is found from the closeness function or an invalid name is input then an error will be returned. The `likeness` query string parameter can be used with this endpoint.
* `/api/subdivision`: get all of the ISO 3166 subdivision data for 1 or more ISO 3166-2 subdivision codes, e.g `/api/subdivision/GB-ABD`. You can also input a comma separated list of subdivision codes from the same and or different countries and the data for each will be returned e.g `/api/subdivision/IE-MO,FI-17,RO-AG`. If the input subdivision code is not in the correct format then an error will be raised. Similarly if an invalid subdivision code that doesn't exist is input then an error will be raised.
* `/api/search/`: get all of the ISO 3166 subdivision data for 1 or more ISO 3166-2 subdivision names that match the inputted search terms, e.g `/api/search/Derry`, `/api/search/Kimpala`. You can also input a comma separated list of subdivision name from the same or different countries and the data for each will be returned e.g `/api/name/Paris,Frankfurt,Rimini`. A closeness function is utilised to find the matching subdivision name, if no exact name match found then the most approximate subdivisions will be returned. Some subdivisions may have the same name, in this case each subdivision and its data will be returned e.g `/api/name/Saint George` (this example returns 5 subdivisions). If an invalid subdivision name that doesn't match any is input then an error will be raised. The `likeness` query string parameter can be used with this endpoint.
* `/api/list_subdivisions`: get list of all the subdivision codes for all countries.
* `/api`: main homepage and API documentation.
### Attributes
There are 8 main default attributes supported for all subdivision objects that will be returned:
* **Code** - ISO 3166-2 subdivision code
* **Name** - subdivision name
* **Local/other name** - subdivision name in local language or any alternative name/nickname it is commonly known by
* **Parent Code** - subdivision parent code
* **Type** - subdivision type, e.g. region, state, canton, parish etc
* **Latitude/Longitude** - subdivision coordinates, from GoogleMaps API
* **Flag** - subdivision flag from the custom-built [`iso3166-flag-icons`](https://github.com/amckenna41/iso3166-flag-icons) repo; this is another ISO 3166 related custom-built dataset of over **3500** regional/subdivision flags
* **History** - historical updates/changes to the subdivision code and naming conventions, as per the custom-built [`iso3166-updates`](https://github.com/amckenna41/iso3166-updates) repo
### Query String Parameters
There are three main query string parameters that can be passed through several of the endpoints of the API:
* **likeness** - this is a value between 1 and 100 that increases or reduces the % of similarity/likeness that the
inputted search terms have to match to the subdivision data in the subdivision code, name and local/other name attributes. This can be used with the `/api/search` and `/api_country_name` endpoints. Having a higher value should return more exact and less total matches and
having a lower value will return less exact but more total matches, e.g ``/api/search/Paris?likeness=50``,
``/api/country_name/Tajikist?likeness=90`` (default=100).
* **filterAttributes** - this is a list of the default supported attributes that you want to include in the output. By default all attributes will be returned but this parameter is useful if you only require a subset of attributes, e.g `api/alpha/DEU?filterAttributes=latLng,flag`, `api/subdivision/PL-02?filterAttributes=localOtherName`.
The API documentation and usage with all useful commands and examples to the API is available on the [API.md][api_md] file.
A demo of the software and API is available [here][demo].
## ISO 3166-2 Scripts
* [`scripts/get_iso3166_2.py`](https://github.com/amckenna41/iso3166-2/blob/main/scripts) - used for pulling and exporting the latest ISO 3166-2 data from the various data sources. In this script you can also export additional attributes for each country/subdivision via the RestCountries and CountryStateCity APIs.
* [`scripts/update_subdivisions.py`](https://github.com/amckenna41/iso3166-2/blob/main/scripts) - used for adding, amending and or deleting subdivisions to the `iso3166-2` software and object.
* [`scripts/local_other_names.py`](https://github.com/amckenna41/iso3166-2/blob/main/scripts/local_other_names.py) - used for adding the data from the local_other_names.csv dataset, including any validation checks on the data.
* [`scripts/utils.py`](https://github.com/amckenna41/iso3166-2/blob/main/scripts/utils.py) - a series of utility functions used throughout the `iso3166-2` project.
* [`scripts/language_lookup.py`](https://github.com/amckenna41/iso3166-2/blob/main/scripts/language_lookup.py) - uses the `local_other_names.csv` dataset to encapsulate and validate the hundreds of language code used throughout the dataset and project.
Please visit the [README](https://github.com/amckenna41/iso3166-2/blob/main/scripts) of the `scripts` folder for more in depth info about the usage and requirements of the above scripts that are <b>vital</b> to the `iso3166-2` software.
## Directories
* `/iso3166_2` - source code for `iso3166-2` software.
* `/scripts` - scripts for the full export pipeline for the ISO 3166-2 subdivision data.
* `/iso3166_2_resources` - several resource/utility and dataset files required for the full export pipeline for the ISO 3166-2 subdivision data.
* `/docs` - documentation for `iso3166-2`, available on [readthedocs](https://iso3166-2.readthedocs.io/en/latest/).
* `/tests` - unit and integration tests for `iso3166-2`
* `UPDATES.md` - markdown file listing all of the additions, amendments and deletions to the ISO 3166-2 dataset (dating from 2022), exported via the [`iso3166-updates`](https://github.com/amckenna41/iso3166-updates) software.
<!-- * `/scripts` - scripts for pulling all the ISO 3166 data (*get_iso3166_2.py*), for adding/amending/deleting subdivisions to the dataset (*update_subdivisions.py*), for adding/validating all the local/other name data in the local_other_names.csv (*local_other_names.py*) and for the various utility functions used throughout the project (*utils.py*). -->
<!-- contains CSV file for listing any changes/updates to be made to the dataset (*subdivision_updates.csv*) via functionality in the /scripts dir, a CSV of all subdivisions and their respective local/other names (local_other_names.csv) and a language lookup file for all the language codes mentioned for any of the local/other names (language_lookup.md). -->
<!-- * `API.md` - info and useful commands/examples for this software's accompanying API - **iso3166-2-api** -->
## Issues or Contributing
Any issues, bugs or enhancements can be raised via the [Issues][issues] tab in the repository. If you would like to contribute any functional/feature changes to the project, please make a Pull Request.
<!-- Also, due to the large amount of data and attributes in the dataset, please raise an Issue if you spot any missing or erroneous data. When raising this Issue please include the current subdivision object attribute values as well as the corrected/new version of them in an easy-to-read format. -->
## Contact
If you have any questions, comments or suggestions, please contact amckenna41@qub.ac.uk or raise an issue in the [Issues][issues] tab. <br><br>
<!-- [](https://www.linkedin.com/in/adam-mckenna-7a5b22151/) -->
## Other ISO 3166 repositories
Below are some of my other **custom-built** repositories that relate to the ISO 3166 standard! ⚡
* [iso3166-2-api](https://github.com/amckenna41/iso3166-2-api): frontend RESTful API for iso3166-2.
* [iso3166-updates](https://github.com/amckenna41/iso3166-update): software and accompanying RESTful API that checks for any updates/changes to the ISO 3166-1 and ISO 3166-2 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).
* [iso3166-updates-api](https://github.com/amckenna41/iso3166-updates-api): frontend RESTful API for iso3166-updates.
* [iso3166-flag-icons](https://github.com/amckenna41/iso3166-flag-icons): a comprehensive library of over 3500 country and regional flags from the ISO 3166-1 and ISO 3166-2 standards.
## References
\[1\]: https://en.wikipedia.org/wiki/ISO_3166 <br>
\[2\]: https://en.wikipedia.org/wiki/ISO_3166-2 <br>
\[3\]: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 <br>
\[4\]: https://www.iso.org/obp/ui/#
## Support
[<img src="https://img.shields.io/github/stars/amckenna41/iso3166-2?color=green&label=star%20it%20on%20GitHub" width="132" height="20" alt="Star it on GitHub">](https://github.com/amckenna41/iso3166-2)
<a href="https://www.buymeacoffee.com/amckenna41" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/default-orange.png" alt="Buy Me A Coffee" height="41" width="174"></a>
[Back to top](#TOP)
[python]: https://www.python.org/downloads/release/python-360/
[iso3166]: https://github.com/deactivated/python-iso3166
[iso3166_2]: https://github.com/amckenna41/iso3166-2
[pycountry]: https://github.com/flyingcircusio/pycountry
[rest]: https://restcountries.com/
[googlemaps]: https://github.com/googlemaps/google-maps-services-python
[tqdm]: https://github.com/tqdm/tqdm
[natsort]: https://pypi.org/project/natsort/
[pandas]: https://pandas.pydata.org/
[unidecode]: https://pypi.org/project/Unidecode/
[thefuzz]: https://github.com/seatgeek/thefuzz/tree/master
[requests]: https://requests.readthedocs.io/
[numpy]: https://numpy.org/
[PyPi]: https://pypi.org/project/iso3166-2/
[iso3166-updates]: https://github.com/amckenna41/iso3166-updates
[demo]: https://colab.research.google.com/drive/1btfEx23bgWdkUPiwdwlDqKkmUp1S-_7U?usp=sharing
[demo_get_iso3166_2]: https://colab.research.google.com/drive/1PXMhpazjsLXVr33RSLZ3w7Tq0RomwPol?usp=sharing
[api]: https://iso3166-2-api.vercel.app/
[api_md]: https://github.com/amckenna41/iso3166-2-api/API.md
[flag_icons_repo]: https://github.com/amckenna41/iso3166-flag-icons
[issues]: https://github.com/amckenna41/iso3166-2/issues
[medium]: https://ajmckenna69.medium.com/iso3166-2-71a13d9157f7
[updates_md]: https://github.com/amckenna41/iso3166-2/blob/main/UPDATES.md
Raw data
{
"_id": null,
"home_page": "https://iso3166-2-api.vercel.app/api",
"name": "iso3166-2",
"maintainer": "AJ McKenna",
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": "amckenna41@qub.ac.uk",
"keywords": "iso, iso3166, beautifulsoup, python, pypi, countries, country codes, iso3166-2, iso3166-1, alpha-2, iso3166-updates, subdivisions, regions, dataset",
"author": "AJ McKenna",
"author_email": "amckenna41@qub.ac.uk",
"download_url": "https://files.pythonhosted.org/packages/ba/46/014799e22d7514168eccf951980f675306acc91f00bb95c7f2e02ac2a824/iso3166_2-1.7.0.tar.gz",
"platform": null,
"description": "<a name=\"TOP\"></a>\n\n# iso 3166-2 \ud83c\udf0e\n\n[](https://pypi.org/project/iso3166-2/)\n[](https://github.com/amckenna41/iso3166-2/actions?query=workflowBuilding%20and%20Testing)\n<!-- [](https://dl.circleci.com/status-badge/redirect/gh/amckenna41/iso3166-2/tree/main) -->\n[](https://pypi.org/project/iso3166-2/)\n[](https://pypi.org/project/iso3166-2/)\n[](https://iso3166-2.readthedocs.io/en/latest/?badge=latest)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/amckenna41/iso3166-2/issues)\n<!-- [](https://github.com/amckenna41/iso3166-2) -->\n<!-- [](https://github.com/iso3166-2) -->\n<!-- [](https://codecov.io/gh/amckenna41/pySAR) -->\n\n<div alt=\"images\" style=\"justify-content: center; display:flex; margin-left=10px;\">\n <img src=\"https://upload.wikimedia.org/wikipedia/commons/3/3d/Flag-map_of_the_world_%282017%29.png\" alt=\"globe\" height=\"300\" width=\"600\"/>\n <!-- <img src=\"https://upload.wikimedia.org/wikipedia/commons/e/e3/ISO_Logo_%28Red_square%29.svg\" alt=\"iso\" height=\"300\" width=\"400\"/> -->\n</div>\n\n> `iso3166-2` is a lightweight custom-built Python package, and accompanying RESTful API, that can be used to access all of the world's ISO 3166-2 subdivision data. A plethora of data attributes are available per country and subdivision including: name, local/other name, code, parent code, type, lat/longitude, flag & history. Currently, the package and API supports data from 250 countries/territories and >5000 subdivisions, according to the ISO 3166-1 & ISO 3166-2 standards, respectively. The software uses another custom-built Python package called [`iso3166-updates`](https://github.com/amckenna41/iso3166-updates/tree/main) to ensure all the subdivision data is accurate, reliable and up-to-date.\n\nQuick Start \ud83c\udfc3\n-------------\n* A <b>demo</b> of the software and API is available [here][demo].\n* The front-end <b>API</b> is available [here][api].\n* The **documentation** for the software & API is available [here](https://iso3166-2.readthedocs.io/en/latest/).\n* A <b>Medium</b> article that dives deeper into `iso3166-2` is available [here][medium].\n<!-- * A <b>demo</b> of the script used to pull and export all the latest ISO 3166-2 data is available [here][demo_get_iso3166_2]. -->\n\nTable of Contents\n-----------------\n- [Introduction](#introduction)\n- [Bespoke Features](#bespoke-features)\n- [Requirements](#requirements)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Documentation](#documentation)\n- [Latest Updates](#latest-updates)\n- [API](#api)\n- [Directories](#directories)\n- [Issues or Contributing](#issues-or-contributing)\n- [Contact](#contact)\n- [References](#references)\n- [Support](#support)\n\n## Introduction\nThe International Organisation for Standards defines codes for the names of countries, dependent territories, special areas of geographical interest, and their principal subdivisions [[1]](#references). The ISO 3166-2 defines codes for identifying the principal subdivisions (e.g. provinces, states, municipalities etc) of all countries coded in the ISO 3166-1. The official name of the standard is <i>\"Codes for the representation of names of countries and their subdivisions \u2013 Part 2: Country subdivision code.\"</i> For some countries, codes are defined for more than one level of subdivisions. \n\nCurrently, this package and accompanying API support subdivision data from **250** officially assigned code elements within the ISO 3166-1, with **200** of these countries having recognised subdivisions (50 entires have 0 subdivisions), totalling **5,049** subdivisions across the whole dataset. Transitional reservations are not included and only 4 of the exceptional reservations, that have now been officially assigned, are included: AX (Aland Islands), GG (Guernsey), IM (Isle of Man) and JE (Jersey) [[3]](#references). The ISO 3166-2 was first published in 1998 and as of **November 2023** there are **5,049** codes defined in it [[2]](#references).\n\nThe full list of subdivision data attributes supported are:\n\n* **Code** - ISO 3166-2 subdivision code\n* **Name** - subdivision name\n* **Local/other name** - subdivision name in local language or any alternative name/nickname it is commonly known by\n* **Parent Code** - subdivision parent code\n* **Type** - subdivision type, e.g. region, state, canton, parish etc\n* **Latitude/Longitude** - subdivision coordinates\n* **Flag** - subdivision flag from [`iso3166-flag-icons`](https://github.com/amckenna41/iso3166-flag-icons) repo; this is another ISO 3166 related custom-built dataset of over **3500** regional/subdivision flags\n* **History** - historical updates/changes to the subdivision code and naming conventions, as per the custom-built [`iso3166-updates`](https://github.com/amckenna41/iso3166-updates) repo.\n\nThe above 8 attributes were chosen as they are the most relevant and useful pieces of data for each subdivision. Other attributes are available in scattered data sources such as area, population, regional name translations, geonames ID, FIPS code etc, but these were deemed less relevant than the ones included... unless someone really desires the population of the Bhutan region of Bumthang (17,820 btw). It was an aim during development to make the package as lightweight as possible, therefore for example if the 5 aforementioned attributes were included for the existing **5,049** codes, this would significantly increase the size of the dataset from **~3MB to ~4MB**. \n\n### Motivation\nThe primary motivation for building this software was for use in my [`iso3166-flag-icons`](https://github.com/amckenna41/iso3166-flag-icons) project. When building the dataset of flags, I found that some existing projects/softwares were **inaccurate**, **outdated** and or **not maintained**. As mentioned, the ISO 3166-2 is a dynamic and ever-changing standard therefore it can be difficult to maintain and keep up-to-date; although in the case for this software, that problem is largely alleviated thanks to the custom-built [`iso3166-updates`](https://github.com/amckenna41/iso3166-updates) package (see below sections).\n\nFurthermore, there are existing toolkits and datasets that offer a rich collection of regional attributes data, [geonames](https://www.geonames.org/) for example. Although, many of these datasets are very large in size and difficult to parse, with an abundance of unessential data attributes. \n\nThus the aim during development was to build a **structured, lightweight and up-to-date ISO 3166-2 dataset with the most sought data attributes that can be easily packaged into a Python package.** \n\n<!-- ### Intended Audience\nThis package is particularly useful for developers and researchers building geographic information systems (GIS), global mapping tools, localization platforms, or projects involving geopolitical datasets. It\u2019s designed to be easily integrated into Python applications with minimal overhead. -->\n\n## Bespoke Features\n\nThere are two 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** and the **flag** attributes.\n\n### Local/Other names\nOne of the most <b>important</b> and <b>bespoke</b> attributes that the software supports, that many others do not, is the **local/other name** attribute. This attribute is built from a custom dataset of local language variants and alternative names/nicknames for the <b>over 5000</b> subdivisions. In total there are <b>>3700</b> local/other names for the <b>>5000</b> subdivisions. Primarily the attribute contains local language translations for the subdivisions, but many also include <b>nicknames</b> and **alternative variants** that the subdivision may be known by, either locally or globally. \n\nFor 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](https://glottolog.org/) or other databases (e.g [IETF](https://support.elucidat.com/hc/en-us/articles/6068623875217-IETF-language-tags)) language codes are used. Some example local/other name entries are: \n* **Sindh (Pakistan PK-SD)**: \"\u0633\u0650\u0646\u0652\u062f\u06be (urd), Sindh (eng), SD (eng), Mehran/Gateway (eng), Bab-ul-Islam/Gateway of Islam (eng)\"\n* **Central Singapore (Singapore SG-01)**: \"Pusat Singapura (msa), \u65b0\u52a0\u5761\u4e2d\u90e8 (zho), \u0bae\u0ba4\u0bcd\u0ba4\u0bbf\u0baf \u0b9a\u0bbf\u0b99\u0bcd\u0b95\u0baa\u0bcd\u0baa\u0bc2\u0bb0\u0bcd (tam)\"\n* **Bobonaro (East Timor TL-BO)**: \"Bobonaru (tet), Buburnaru (tet), Tall eucalypt (eng)\"\n* **Wyoming (USA US-WY)** - \"Equality State (eng), Cowboy State (eng), Big Wyoming (eng)\"\n\nThe full dataset of local/other names is available in the repo here [`local_other_names.csv`](https://github.com/amckenna41/iso3166-2/iso3166_2_resources/local_other_names.csv)\n\n###\u00a0Flags\nThe 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-flag-icons`](https://github.com/amckenna41/iso3166-flag-icons) repo. This is another **custom-built** repository, (alongside [`iso3166-2`](https://github.com/amckenna41/iso3166-2) and [`iso3166-updates`](https://github.com/amckenna41/iso3166-updates)) that stores a rich and comprehensive dataset of over **3500** individual subdivision flags. \n\nThe 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. \n\n <div align=\"center\">\u2764\ufe0f iso3166-2 \ud83e\udd1d iso3166-updates \ud83e\udd1d iso3166-flag-icons \u2764\ufe0f</div>\n \n## Requirements\n* [python][python] >= 3.9\n* [iso3166][iso3166] >= 2.1.1\n* [natsort][natsort] >= 8.4.0\n* [thefuzz][thefuzz] >= 0.22.1\n* [requests][requests] >= 2.28.1\n<!-- * [unidecode][unidecode] >= 1.3.8 -->\n\n## Installation\nInstall the latest version of `iso3166-2` via [PyPi][PyPi] using pip:\n\n```bash\npip install iso3166-2 --upgrade\n```\n\n## Usage\nAll of the country's subdivision data and attributes are encapsulated into an instance of the *Subdivisions* class via the JSON object **iso3166-2.json**, which contains each country's ISO 3166-2 subdivision data. The data can be accessed after creating an instance of the <i>Subdivisions</i> class, with the instance being subscriptable such that data can be accessed via their ISO 3166-1 alpha-2, alpha-3 or numeric country codes. There also exist a plethora of additional functionalities around the subdivisision data. Below are some usage examples for the software.\n\n**Import and create instance of Subdivisions class:**\n```python\nfrom iso3166_2 import *\n\n#create instance of Subdivisions class\niso = Subdivisions()\n```\n\n**Get all ISO 3166-2 data for all countries:**\n```python\niso.all\n```\n\n**Get all subdivision data for a country, via their alpha-2, alpha-3 and numeric country codes:**\n```python\ncanada_iso3166_2 = iso[\"CA\"]\ndenmark_iso3166_2 = iso[\"DK\"]\nestonia_iso3166_2 = iso[\"EST\"]\nperu_iso3166_2 = iso[\"PER\"]\nfiji_haiti_iso3166_2 = iso[\"FJ, HT\"]\nfiji_haiti_guyana_iso3166_2 = iso[\"FJ, HTI, 328\"]\n```\n\n**Get subdivision's data, via its subdivision code:**\n```python\niso[\"CA\"]['CA-AB'] #Alberta subdivision\niso[\"DK\"]['DK-81'] #Nordjylland subdivision\niso[\"EST\"]['EE-899'] #Viljandi subdivision\niso[\"FJI\"]['FJ-03'] #Cakaudrove subdivision \niso[\"PE\"][\"PE-LAL\"] #La Libertad subdivision\niso[\"604\"]['PE-AMA'] #Amarumayu subdivision\n```\n\n**Get individual attribute values per subdivision:**\n```python\niso[\"CA\"]['CA-AB'].latLng #Alberta subdivision latitude/longitude\niso[\"DK\"]['DK-81'].flag #Nordjylland subdivision flag URL\niso[\"PE\"]['PE-LAL'].history #La Libertad subdivision updates history\niso[\"EST\"]['EE-899'].name #Viljandi subdivision name\niso[\"FJI\"]['FJ-03'].type #Cakaudrove subdivision type\niso[\"604\"]['PE-AMA'].parentCode #Amarumayu subdivision\n```\n\n**Get subset of subdivision attributes for all countries:**\n```python\n'''\nIf only a subset of the available default attributes are required per\nsubdivision, include them via the 'filter_attributes' input parameter\nwhen creating an instance of the class. All attributes not included\nin this list will be excluded.\n'''\nfrom iso3166_2 import *\n\n#create instance of Subdivisions class\niso = Subdivisions(filter_attributes=\"flag,parentCode,type\")\n```\n\n**Searching for a specific subdivision via its subdivision name or local/other name attributes:**\n```python\n'''\nThe search functionality will search over all subdivisions in the object, \nreturning either a subdivision with the exact match or subdivisions whose names \napproximately match the sought input name according to the likeness input parameter.\nThe likeness input parameter is a % similarity the input search terms have to be to \nthe subdivision names, with 100% being an exact match, vice versa. Reducing this\nvalue will thus increase the search space and return more like results.\n'''\nfrom iso3166_2 import *\n\n#create instance of Subdivisions class\niso = Subdivisions()\n\n#searching for the Monaghan county in Ireland (IE-MN) - returning exact matching subdivision (likeness=100)\niso.search(\"Monaghan\")\n\n#searching for Castelo Branco district in Portugal (PT-05) - returning exact matching subdivision (likeness=100)\niso.search(\"Castelo Branco\", likeness=100)\n\n#searching for the Roche Caiman district in Seychelles (SC-25) - returning exact matching subdivision (likeness=100)\niso.search(\"Roche Caiman\")\n\n#searching for any subdivisions that have \"Southern\" in their name, using a likeness score of 80\niso.search(\"Southern\", likeness_score=80)\n\n#searching for any subdivisions that have \"City\" in their name or localOtherName attributes, using a likeness score of 40%\niso.search(\"City\", likeness=40, local_other_name_search=True)\n\n#searching for state of Texas and French Department Meuse - both subdivision objects will be returned, only including the subdivision type and name attributes\niso.search(\"Texas, Meuse\", filter_attributes=\"name,type\") \n```\n\n**Adding a custom subdivision to the iso3166-2 object:**\n```python\n'''\nThe context for this functionality is similar to that of the user-assigned \ncode elements of the ISO 3166-1 standard. Custom subdivisions and subdivision \ncodes can be used for in-house/bespoke applications that are using the \niso3166-2 software but require additional custom subdivisions to be represented.\nYou can also add custom attributes for the custom subdivision, e.g population,\narea, gdp etc, via the custom_attribute parameter.\n'''\nfrom iso3166_2 import *\n\n#create instance of Subdivisions class\niso = Subdivisions()\n\n#adding custom Belfast province to Ireland\niso.custom_subdivision(\"IE\", \"IE-BF\", name=\"Belfast\", local_name=\"B\u00e9al Feirste\", type_=\"province\", lat_lng=[54.596, -5.931], parent_code=None, flag=None)\n\n#adding custom Alaska province to Russia with additional population and area attribute values\niso.custom_subdivision(\"RU\", \"RU-ASK\", name=\"Alaska Oblast\", local_other_name=\"\u0410\u043b\u044f\u0441\u043a\u0430\", type_=\"Republic\", lat_lng=[63.588, 154.493], parent_code=None, flag=None, \n custom_attributes={\"population\": \"733,583\", \"gini\": \"0.43\", \"gdpPerCapita\": \"71,996\"})\n\n#adding custom Republic of Molossia state to United States \niso.custom_subdivision(\"US\", \"US-ML\", name=\"Republic of Molossia\", local_name=\"\", type_=\"State\", lat_lng=[39.236, -119.588], parent_code=None, flag=\"https://upload.wikimedia.org/wikipedia/commons/c/c3/Flag_of_the_Republic_of_Molossia.svg\")\n\n#deleting above custom subdivisions from object\niso.custom_subdivision(\"IE\", \"IE-BF\", delete=1)\niso.custom_subdivision(\"US\", \"US-ML\", delete=1)\niso.custom_subdivision(\"RU\", \"RU-ASK\", delete=1)\n\n```\n**Check for the latest updates data from the repository:**\n```python\n'''\nCompare the subdivision data in the current installed version of the \niso3166-2 software with the most up-to-date and accurate version on\nthe repository. If there are any difference between these objects,\nthey will be output.\n'''\niso.check_for_updates()\n```\n\n**Get total number of subdivisions in object:**\n```python\nlen(iso)\n```\n\n**Get size of dataset in MB:**\n```python\n\niso.__sizeof__()\n```\n\n## Documentation\nDocumentation for installation and usage of the software and API is available on the readthedocs platform:\n\n<b>https://iso3166-2.readthedocs.io/en/latest/</b>\n\n## Latest Updates\nAn important thing to note about the ISO 3166-2 and its subdivision codes/names is that changes are made consistently to it, from a small subdivision name change to an addition/deletion of a whole subdivision. These changes can happen due for a variety of geopolitical and administrative reasons. Therefore, it's important that this library and its JSON have the most **up-to-date, accurate and reliable data**. To achieve this, the custom-built [`iso3166-updates`](https://github.com/amckenna41/iso3166-updates) repo was created!\n\nThe [`iso3166-updates`](https://github.com/amckenna41/iso3166-updates) repo is another open-source software package and accompanying RESTful API that pulls the latest updates and changes for any and all countries in the ISO 3166 from a variety of data sources including the ISO website itself. A script is called periodically to check for any updates/changes to the subdivisions, which are communicated via the ISO's Online Browsing Platform [[4]](#references), and will then be manually incorporated into this repo. Please visit the repository home page for more info about the purpose and process of the software and API - [`iso3166-updates`](https://github.com/amckenna41/iso3166-updates).\n\nThe list of ISO 3166 updates was last updated on <strong>November 2024</strong>. A log of the latest ISO 3166 updates can be seen in the [UPDATES.md][updates_md] file.\n\n## API\nThe main API endpoint is:\n\n> [https://iso3166-2-api.vercel.app/api](https://iso3166-2-api.vercel.app/api)\n\nThe other endpoints available in the API are:\n* https://iso3166-2-api.vercel.app/api/all\n* https://iso3166-2-api.vercel.app/api/alpha/<input_alpha>\n* https://iso3166-2-api.vercel.app/api/country_name/<input_country_name>\n* https://iso3166-2-api.vercel.app/api/subdivision/<input_subdivision>\n* https://iso3166-2-api.vercel.app/api/search/<input_search_name>\n* https://iso3166-2-api.vercel.app/api/list_subdivisions\n\nSix paths/endpoints are available in the API - `/api/all`, `/api/alpha`, `/api/country_name`, `/api/subdivision`, `/api/search` and `/api/list_subdivisions`.\n\n* `/api/all`: get all of the ISO 3166 subdivision data for all countries.\n\n* `/api/alpha`: get all of the ISO 3166 subdivision data for 1 or more inputted ISO 3166-1 alpha-2, alpha-3 or numeric country codes, e.g. `/api/alpha/FR,DE,HU,ID,MA`, `/api/alpha/FRA,DEU,HUN,IDN,MAR` and `/api/alpha/428,504,638`. A comma separated list of multiple alpha codes can also be input. If an invalid country code is input then an error will be returned.\n\n* `/api/country_name`: get all of the ISO 3166 subdivision data for 1 or more inputted ISO 3166-1 country names, as they are commonly known in English, e.g. `/api/country_name/France,Moldova,Benin`. A comma separated list of country names can also be input. A closeness function is utilised so the most approximate name from the input will be used e.g. Sweden will be returned if the input is `/api/country_name/Swede`. If no country is found from the closeness function or an invalid name is input then an error will be returned. The `likeness` query string parameter can be used with this endpoint.\n\n* `/api/subdivision`: get all of the ISO 3166 subdivision data for 1 or more ISO 3166-2 subdivision codes, e.g `/api/subdivision/GB-ABD`. You can also input a comma separated list of subdivision codes from the same and or different countries and the data for each will be returned e.g `/api/subdivision/IE-MO,FI-17,RO-AG`. If the input subdivision code is not in the correct format then an error will be raised. Similarly if an invalid subdivision code that doesn't exist is input then an error will be raised.\n\n* `/api/search/`: get all of the ISO 3166 subdivision data for 1 or more ISO 3166-2 subdivision names that match the inputted search terms, e.g `/api/search/Derry`, `/api/search/Kimpala`. You can also input a comma separated list of subdivision name from the same or different countries and the data for each will be returned e.g `/api/name/Paris,Frankfurt,Rimini`. A closeness function is utilised to find the matching subdivision name, if no exact name match found then the most approximate subdivisions will be returned. Some subdivisions may have the same name, in this case each subdivision and its data will be returned e.g `/api/name/Saint George` (this example returns 5 subdivisions). If an invalid subdivision name that doesn't match any is input then an error will be raised. The `likeness` query string parameter can be used with this endpoint. \n\n* `/api/list_subdivisions`: get list of all the subdivision codes for all countries. \n\n* `/api`: main homepage and API documentation.\n\n### Attributes\nThere are 8 main default attributes supported for all subdivision objects that will be returned:\n\n* **Code** - ISO 3166-2 subdivision code\n* **Name** - subdivision name\n* **Local/other name** - subdivision name in local language or any alternative name/nickname it is commonly known by\n* **Parent Code** - subdivision parent code\n* **Type** - subdivision type, e.g. region, state, canton, parish etc\n* **Latitude/Longitude** - subdivision coordinates, from GoogleMaps API\n* **Flag** - subdivision flag from the custom-built [`iso3166-flag-icons`](https://github.com/amckenna41/iso3166-flag-icons) repo; this is another ISO 3166 related custom-built dataset of over **3500** regional/subdivision flags\n* **History** - historical updates/changes to the subdivision code and naming conventions, as per the custom-built [`iso3166-updates`](https://github.com/amckenna41/iso3166-updates) repo\n\n### Query String Parameters\nThere are three main query string parameters that can be passed through several of the endpoints of the API:\n\n* **likeness** - this is a value between 1 and 100 that increases or reduces the % of similarity/likeness that the \ninputted search terms have to match to the subdivision data in the subdivision code, name and local/other name attributes. This can be used with the `/api/search` and `/api_country_name` endpoints. Having a higher value should return more exact and less total matches and \nhaving a lower value will return less exact but more total matches, e.g ``/api/search/Paris?likeness=50``, \n``/api/country_name/Tajikist?likeness=90`` (default=100).\n* **filterAttributes** - this is a list of the default supported attributes that you want to include in the output. By default all attributes will be returned but this parameter is useful if you only require a subset of attributes, e.g `api/alpha/DEU?filterAttributes=latLng,flag`, `api/subdivision/PL-02?filterAttributes=localOtherName`.\n\nThe API documentation and usage with all useful commands and examples to the API is available on the [API.md][api_md] file. \n\nA demo of the software and API is available [here][demo].\n\n\n## ISO 3166-2 Scripts\n* [`scripts/get_iso3166_2.py`](https://github.com/amckenna41/iso3166-2/blob/main/scripts) - used for pulling and exporting the latest ISO 3166-2 data from the various data sources. In this script you can also export additional attributes for each country/subdivision via the RestCountries and CountryStateCity APIs.\n* [`scripts/update_subdivisions.py`](https://github.com/amckenna41/iso3166-2/blob/main/scripts) - used for adding, amending and or deleting subdivisions to the `iso3166-2` software and object.\n* [`scripts/local_other_names.py`](https://github.com/amckenna41/iso3166-2/blob/main/scripts/local_other_names.py) - used for adding the data from the local_other_names.csv dataset, including any validation checks on the data.\n* [`scripts/utils.py`](https://github.com/amckenna41/iso3166-2/blob/main/scripts/utils.py) - a series of utility functions used throughout the `iso3166-2` project.\n* [`scripts/language_lookup.py`](https://github.com/amckenna41/iso3166-2/blob/main/scripts/language_lookup.py) - uses the `local_other_names.csv` dataset to encapsulate and validate the hundreds of language code used throughout the dataset and project.\n\n\nPlease visit the [README](https://github.com/amckenna41/iso3166-2/blob/main/scripts) of the `scripts` folder for more in depth info about the usage and requirements of the above scripts that are <b>vital</b> to the `iso3166-2` software.\n\n## Directories\n* `/iso3166_2` - source code for `iso3166-2` software.\n* `/scripts` - scripts for the full export pipeline for the ISO 3166-2 subdivision data. \n* `/iso3166_2_resources` - several resource/utility and dataset files required for the full export pipeline for the ISO 3166-2 subdivision data. \n* `/docs` - documentation for `iso3166-2`, available on [readthedocs](https://iso3166-2.readthedocs.io/en/latest/).\n* `/tests` - unit and integration tests for `iso3166-2`\n* `UPDATES.md` - markdown file listing all of the additions, amendments and deletions to the ISO 3166-2 dataset (dating from 2022), exported via the [`iso3166-updates`](https://github.com/amckenna41/iso3166-updates) software.\n\n<!-- * `/scripts` - scripts for pulling all the ISO 3166 data (*get_iso3166_2.py*), for adding/amending/deleting subdivisions to the dataset (*update_subdivisions.py*), for adding/validating all the local/other name data in the local_other_names.csv (*local_other_names.py*) and for the various utility functions used throughout the project (*utils.py*). -->\n<!-- contains CSV file for listing any changes/updates to be made to the dataset (*subdivision_updates.csv*) via functionality in the /scripts dir, a CSV of all subdivisions and their respective local/other names (local_other_names.csv) and a language lookup file for all the language codes mentioned for any of the local/other names (language_lookup.md). -->\n<!-- * `API.md` - info and useful commands/examples for this software's accompanying API - **iso3166-2-api** -->\n\n## Issues or Contributing\nAny issues, bugs or enhancements can be raised via the [Issues][issues] tab in the repository. If you would like to contribute any functional/feature changes to the project, please make a Pull Request.\n\n<!-- Also, due to the large amount of data and attributes in the dataset, please raise an Issue if you spot any missing or erroneous data. When raising this Issue please include the current subdivision object attribute values as well as the corrected/new version of them in an easy-to-read format. -->\n\n## Contact\nIf you have any questions, comments or suggestions, please contact amckenna41@qub.ac.uk or raise an issue in the [Issues][issues] tab. <br><br>\n<!-- [](https://www.linkedin.com/in/adam-mckenna-7a5b22151/) -->\n\n## Other ISO 3166 repositories\nBelow are some of my other **custom-built** repositories that relate to the ISO 3166 standard! \u26a1\n\n* [iso3166-2-api](https://github.com/amckenna41/iso3166-2-api): frontend RESTful API for iso3166-2.\n* [iso3166-updates](https://github.com/amckenna41/iso3166-update): software and accompanying RESTful API that checks for any updates/changes to the ISO 3166-1 and ISO 3166-2 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).\n* [iso3166-updates-api](https://github.com/amckenna41/iso3166-updates-api): frontend RESTful API for iso3166-updates.\n* [iso3166-flag-icons](https://github.com/amckenna41/iso3166-flag-icons): a comprehensive library of over 3500 country and regional flags from the ISO 3166-1 and ISO 3166-2 standards.\n\n## References\n\\[1\\]: https://en.wikipedia.org/wiki/ISO_3166 <br>\n\\[2\\]: https://en.wikipedia.org/wiki/ISO_3166-2 <br>\n\\[3\\]: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 <br>\n\\[4\\]: https://www.iso.org/obp/ui/#\n\n## Support\n[<img src=\"https://img.shields.io/github/stars/amckenna41/iso3166-2?color=green&label=star%20it%20on%20GitHub\" width=\"132\" height=\"20\" alt=\"Star it on GitHub\">](https://github.com/amckenna41/iso3166-2)\n\n<a href=\"https://www.buymeacoffee.com/amckenna41\" target=\"_blank\"><img src=\"https://cdn.buymeacoffee.com/buttons/default-orange.png\" alt=\"Buy Me A Coffee\" height=\"41\" width=\"174\"></a>\n\n[Back to top](#TOP)\n\n[python]: https://www.python.org/downloads/release/python-360/\n[iso3166]: https://github.com/deactivated/python-iso3166\n[iso3166_2]: https://github.com/amckenna41/iso3166-2\n[pycountry]: https://github.com/flyingcircusio/pycountry\n[rest]: https://restcountries.com/\n[googlemaps]: https://github.com/googlemaps/google-maps-services-python\n[tqdm]: https://github.com/tqdm/tqdm\n[natsort]: https://pypi.org/project/natsort/\n[pandas]: https://pandas.pydata.org/\n[unidecode]: https://pypi.org/project/Unidecode/\n[thefuzz]: https://github.com/seatgeek/thefuzz/tree/master\n[requests]: https://requests.readthedocs.io/\n[numpy]: https://numpy.org/\n[PyPi]: https://pypi.org/project/iso3166-2/\n[iso3166-updates]: https://github.com/amckenna41/iso3166-updates\n[demo]: https://colab.research.google.com/drive/1btfEx23bgWdkUPiwdwlDqKkmUp1S-_7U?usp=sharing\n[demo_get_iso3166_2]: https://colab.research.google.com/drive/1PXMhpazjsLXVr33RSLZ3w7Tq0RomwPol?usp=sharing\n[api]: https://iso3166-2-api.vercel.app/\n[api_md]: https://github.com/amckenna41/iso3166-2-api/API.md \n[flag_icons_repo]: https://github.com/amckenna41/iso3166-flag-icons\n[issues]: https://github.com/amckenna41/iso3166-2/issues\n[medium]: https://ajmckenna69.medium.com/iso3166-2-71a13d9157f7\n[updates_md]: https://github.com/amckenna41/iso3166-2/blob/main/UPDATES.md",
"bugtrack_url": null,
"license": "MIT",
"summary": "A lightweight Python package, and accompanying API, used to access all of the world's most up-to-date and accurate ISO 3166-2 subdivision data, including: name, local/other name, code, parent code, type, latitude/longitude, flag and history.",
"version": "1.7.0",
"project_urls": {
"Homepage": "https://iso3166-2-api.vercel.app/api",
"documentation": "https://iso3166-2.readthedocs.io/en/latest/",
"repository": "https://github.com/amckenna41/iso3166-2"
},
"split_keywords": [
"iso",
" iso3166",
" beautifulsoup",
" python",
" pypi",
" countries",
" country codes",
" iso3166-2",
" iso3166-1",
" alpha-2",
" iso3166-updates",
" subdivisions",
" regions",
" dataset"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8c150f9bcc55a5548d7ca3f9fa06fd434c4ff38d7ae2c7df83666c2af22e25b9",
"md5": "a853493cec46f3a57938819580aa9f8a",
"sha256": "8a4b8a8345a9e57ad7dfc744c16ed99494b0214d35d457db3085570ce0990c77"
},
"downloads": -1,
"filename": "iso3166_2-1.7.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a853493cec46f3a57938819580aa9f8a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 287032,
"upload_time": "2025-07-18T11:49:55",
"upload_time_iso_8601": "2025-07-18T11:49:55.429105Z",
"url": "https://files.pythonhosted.org/packages/8c/15/0f9bcc55a5548d7ca3f9fa06fd434c4ff38d7ae2c7df83666c2af22e25b9/iso3166_2-1.7.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ba46014799e22d7514168eccf951980f675306acc91f00bb95c7f2e02ac2a824",
"md5": "799fe01da6fdcfec238135e9223ffb45",
"sha256": "5ba0b94086dac352b49aceb3c00261d745f971964ef417a8a23f924ad3d056cf"
},
"downloads": -1,
"filename": "iso3166_2-1.7.0.tar.gz",
"has_sig": false,
"md5_digest": "799fe01da6fdcfec238135e9223ffb45",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 284717,
"upload_time": "2025-07-18T11:49:56",
"upload_time_iso_8601": "2025-07-18T11:49:56.880440Z",
"url": "https://files.pythonhosted.org/packages/ba/46/014799e22d7514168eccf951980f675306acc91f00bb95c7f2e02ac2a824/iso3166_2-1.7.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-18 11:49:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "amckenna41",
"github_project": "iso3166-2",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "iso3166-2"
}
