### Install iso3166-2

Source: https://iso3166-2.readthedocs.io/en/latest/_sources/usage.rst.txt

Install the package using pip.

```console
pip install iso3166-2
```

--------------------------------

### Access CLI help and installation

Source: https://iso3166-2.readthedocs.io/en/latest/troubleshooting.html

Commands for accessing help documentation and installing the package in editable mode.

```bash
iso3166-2 --help
iso3166-2 search --help
iso3166-2 reverse --help
```

```bash
pip install -e .
```

--------------------------------

### GET /api/all

Source: https://iso3166-2.readthedocs.io/en/latest/api.html

Retrieves all available country data.

```APIDOC
## GET /api/all

### Description
Retrieves all available country data from the API.

### Method
GET

### Endpoint
https://iso3166-2-api.vercel.app/api/all

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Limits the total number of countries returned. Default is None.
- **filterAttributes** (string) - Optional - Allows including only a subset of desired attributes per subdivision.
```

--------------------------------

### GET /api/all

Source: https://iso3166-2.readthedocs.io/en/latest/_sources/api.rst.txt

Retrieves all available subdivision data for all countries.

```APIDOC
## GET /api/all

### Description
Return all available subdivision data for all countries.

### Method
GET

### Endpoint
/api/all

### Parameters
#### Query Parameters
- **filterAttributes** (string) - Optional - A subset of desired attributes per subdivision to include in the output.
- **limit** (integer) - Optional - The total number of countries to return (default=None).
```

--------------------------------

### GET /api/list_subdivisions/<input_alpha>

Source: https://iso3166-2.readthedocs.io/en/latest/_sources/api.rst.txt

Get a list of all subdivision codes for all countries.

```APIDOC
## GET /api/list_subdivisions/<input_alpha>

### Description
Get list of all the subdivision codes for all countries.

### Method
GET

### Endpoint
/api/list_subdivisions/<input_alpha>
```

--------------------------------

### GET /api/all

Source: https://iso3166-2.readthedocs.io/en/latest/_sources/api.rst.txt

Retrieve all ISO 3166 subdivision data for all countries.

```APIDOC
## GET /api/all

### Description
Get all of the ISO 3166 subdivision data for all countries.

### Method
GET

### Endpoint
/api/all
```

--------------------------------

### GET /api/all

Source: https://iso3166-2.readthedocs.io/en/latest/api.html

Retrieves all available subdivision data for all countries.

```APIDOC
## GET /api/all

### Description
Returns all available subdivision data for all countries.

### Method
GET

### Endpoint
https://iso3166-2-api.vercel.app/api/all
```

--------------------------------

### GET /api/country_name/<input_country_name>

Source: https://iso3166-2.readthedocs.io/en/latest/api.html

Retrieves data for a country by its name.

```APIDOC
## GET /api/country_name/<input_country_name>

### Description
Retrieves data for a country by its name.

### Method
GET

### Endpoint
https://iso3166-2-api.vercel.app/api/country_name/<input_country_name>

### Parameters
#### Path Parameters
- **input_country_name** (string) - Required - The country name to query.

#### Query Parameters
- **likeness** (integer) - Optional - Similarity percentage (1-100) for matching. Default is 100.
- **filterAttributes** (string) - Optional - Allows including only a subset of desired attributes per subdivision.
```

--------------------------------

### Get list of all subdivision codes per country

Source: https://iso3166-2.readthedocs.io/en/latest/api.html

Fetch ISO 3166-2 subdivision codes for all countries or filter by a specific ISO 3166-1 country code.

```python
import requests

base_url = "https://iso3166-2-api.vercel.app/api/list_subdivisions"
all_data = requests.get(base_url)

all_data["DE"] #subdivision codes for Germany
all_data["OM"] #subdivision data for Oman
all_data["US"] #subdivision data for US

#get specific subdivision list via country code
base_url = "https://iso3166-2-api.vercel.app/api/list_subdivisions/DE"
all_data = requests.get(base_url)

base_url = "https://iso3166-2-api.vercel.app/api/list_subdivisions/OM"
all_data = requests.get(base_url)

base_url = "https://iso3166-2-api.vercel.app/api/list_subdivisions/US"
all_data = requests.get(base_url)
```

```bash
$ curl -i https://iso3166-2-api.vercel.app/api/list_subdivisions
$ curl -i https://iso3166-2-api.vercel.app/api/list_subdivisions/DE
$ curl -i https://iso3166-2-api.vercel.app/api/list_subdivisions/OM
$ curl -i https://iso3166-2-api.vercel.app/api/list_subdivisions/US
```

--------------------------------

### GET /api/subdivision/<input_subdivision>

Source: https://iso3166-2.readthedocs.io/en/latest/api.html

Retrieves data for a specific subdivision.

```APIDOC
## GET /api/subdivision/<input_subdivision>

### Description
Retrieves data for a specific subdivision by its code.

### Method
GET

### Endpoint
https://iso3166-2-api.vercel.app/api/subdivision/<input_subdivision>

### Parameters
#### Path Parameters
- **input_subdivision** (string) - Required - The subdivision code to query.

#### Query Parameters
- **filterAttributes** (string) - Optional - Allows including only a subset of desired attributes per subdivision.
```

--------------------------------

### Check for subdivision data updates

Source: https://iso3166-2.readthedocs.io/en/latest/_sources/usage.rst.txt

Compares the currently installed subdivision data against the latest version available in the GitHub repository.

```python
from iso3166_2 import *

#create instance of Subdivisions class
iso = Subdivisions()

#compare latest subdivision data from repo
iso.check_for_updates()
```

--------------------------------

### GET /api/list_subdivisions/{country_code}

Source: https://iso3166-2.readthedocs.io/en/latest/_sources/api.rst.txt

Retrieve a list of all ISO 3166-2 subdivision codes for a specific country or all countries.

```APIDOC
## GET /api/list_subdivisions/{country_code}

### Description
Return a list of all ISO 3166-2 subdivision codes for each country. If a country code is provided, it returns the list for that specific country.

### Method
GET

### Endpoint
https://iso3166-2-api.vercel.app/api/list_subdivisions/{country_code}

### Parameters
#### Path Parameters
- **country_code** (string) - Optional - The ISO 3166-1 country code to filter subdivisions.
```

--------------------------------

### GET /api/list_subdivisions/<input_alpha>

Source: https://iso3166-2.readthedocs.io/en/latest/api.html

Lists all subdivisions for a given country alpha code.

```APIDOC
## GET /api/list_subdivisions/<input_alpha>

### Description
Lists all subdivisions associated with the provided country alpha code.

### Method
GET

### Endpoint
https://iso3166-2-api.vercel.app/api/list_subdivisions/<input_alpha>

### Parameters
#### Path Parameters
- **input_alpha** (string) - Required - The country alpha code.

#### Query Parameters
- **filterAttributes** (string) - Optional - Allows including only a subset of desired attributes per subdivision.
```

--------------------------------

### GET /api/search/{query}

Source: https://iso3166-2.readthedocs.io/en/latest/_sources/api.rst.txt

Search for a specific ISO 3166-2 subdivision by name or code.

```APIDOC
## GET /api/search/{query}

### Description
Search for a specific ISO 3166-2 subdivision. Input can be a comma separated list of subdivision names or ISO 3166-2 subdivision codes.

### Method
GET

### Endpoint
https://iso3166-2-api.vercel.app/api/search/{query}

### Parameters
#### Path Parameters
- **query** (string) - Required - The subdivision name or ISO 3166-2 code to search for.

#### Query Parameters
- **excludeMatchScore** (integer) - Optional - Parameter to exclude match score from results.
- **likeness** (integer) - Optional - Likeness score for approximate search.
```

--------------------------------

### Retrieve all subdivision data

Source: https://iso3166-2.readthedocs.io/en/latest/_sources/usage.rst.txt

Access the all attribute of the Subdivisions class to get data for all countries using various ISO 3166-1 codes.

```python
from iso3166_2 import *

#crete instance of Subdivisions class
iso = Subdivisions()

all_data = iso.all

all_data["LU"] #all subdivision data for Luxembourg
all_data["PW"] #all subdivision data for Palau
all_data["TUV"] #all subdivision data for Tuvalu
all_data["UKR"] #all subdivision data for Ukraine
all_data["876"] #all subdivision data for Wallis & Futuna
all_data["716"] #all subdivision data for Zimbabwe
```

--------------------------------

### GET /api/search/<input_search>

Source: https://iso3166-2.readthedocs.io/en/latest/api.html

Searches for subdivisions based on input terms.

```APIDOC
## GET /api/search/<input_search>

### Description
Searches for subdivisions based on the provided search terms.

### Method
GET

### Endpoint
https://iso3166-2-api.vercel.app/api/search/<input_search>

### Parameters
#### Path Parameters
- **input_search** (string) - Required - The search term.

#### Query Parameters
- **likeness** (integer) - Optional - Similarity percentage (1-100) for matching. Default is 100.
- **filterAttributes** (string) - Optional - Allows including only a subset of desired attributes per subdivision.
- **excludeMatchScore** (boolean) - Optional - Excludes the matchScore attribute from results. Default is 0.
```

--------------------------------

### GET /api/subdivision/<input_subdivision>

Source: https://iso3166-2.readthedocs.io/en/latest/_sources/api.rst.txt

Retrieve subdivision data for specific ISO 3166-2 subdivision codes.

```APIDOC
## GET /api/subdivision/<input_subdivision>

### Description
Get all of the ISO 3166 subdivision data for 1 or more ISO 3166-2 subdivision codes. You can input a comma separated list of subdivision codes.

### Method
GET

### Endpoint
/api/subdivision/<input_subdivision>

### Parameters
#### Path Parameters
- **input_subdivision** (string) - Required - Comma separated list of ISO 3166-2 subdivision codes.
```

--------------------------------

### GET /api/alpha/<input_alpha>

Source: https://iso3166-2.readthedocs.io/en/latest/api.html

Retrieves data for a specific country or set of countries by alpha code.

```APIDOC
## GET /api/alpha/<input_alpha>

### Description
Retrieves data for a specific country or set of countries using their alpha code.

### Method
GET

### Endpoint
https://iso3166-2-api.vercel.app/api/alpha/<input_alpha>

### Parameters
#### Path Parameters
- **input_alpha** (string) - Required - The alpha code(s) to query.

#### Query Parameters
- **filterAttributes** (string) - Optional - Allows including only a subset of desired attributes per subdivision.
```

--------------------------------

### GET /api/search_geo/<input_search>

Source: https://iso3166-2.readthedocs.io/en/latest/api.html

Performs a geographical search for subdivisions.

```APIDOC
## GET /api/search_geo/<input_search>

### Description
Performs a geographical search for subdivisions based on the provided search terms.

### Method
GET

### Endpoint
https://iso3166-2-api.vercel.app/api/search_geo/<input_search>

### Parameters
#### Path Parameters
- **input_search** (string) - Required - The search term.

#### Query Parameters
- **filterAttributes** (string) - Optional - Allows including only a subset of desired attributes per subdivision.
```

--------------------------------

### GET /api/country_name/<input_country_name>

Source: https://iso3166-2.readthedocs.io/en/latest/_sources/api.rst.txt

Retrieve subdivision data for countries using their English names.

```APIDOC
## GET /api/country_name/<input_country_name>

### Description
Get all of the ISO 3166 subdivision data for 1 or more inputted ISO 3166-1 country names. A closeness function is utilized to match the input name.

### Method
GET

### Endpoint
/api/country_name/<input_country_name>

### Parameters
#### Path Parameters
- **input_country_name** (string) - Required - Comma separated list of country names.
```

--------------------------------

### GET /api/alpha/<input_alpha>

Source: https://iso3166-2.readthedocs.io/en/latest/_sources/api.rst.txt

Retrieve subdivision data for specific countries using ISO 3166-1 alpha-2, alpha-3, or numeric codes.

```APIDOC
## GET /api/alpha/<input_alpha>

### Description
Get all of the ISO 3166 subdivision data for 1 or more inputted ISO 3166-1 alpha-2, alpha-3 or numeric country codes. A comma separated list of multiple alpha codes can also be input.

### Method
GET

### Endpoint
/api/alpha/<input_alpha>

### Parameters
#### Path Parameters
- **input_alpha** (string) - Required - Comma separated list of ISO 3166-1 country codes (alpha-2, alpha-3, or numeric).
```

--------------------------------

### GET /api/search/<input_search>

Source: https://iso3166-2.readthedocs.io/en/latest/_sources/api.rst.txt

Search for subdivision data using subdivision names or search terms.

```APIDOC
## GET /api/search/<input_search>

### Description
Get all of the ISO 3166 subdivision data for 1 or more ISO 3166-2 subdivision names or input search terms. A closeness function is utilized to find matching subdivisions.

### Method
GET

### Endpoint
/api/search/<input_search>

### Parameters
#### Path Parameters
- **input_search** (string) - Required - Comma separated list of subdivision names or search terms.

#### Query Parameters
- **likeness** (integer) - Optional - Likeness score between 1-100 to control match tolerance.
```

--------------------------------

### GET /api/search_geo/<input_search>

Source: https://iso3166-2.readthedocs.io/en/latest/_sources/api.rst.txt

Search for subdivisions and return only geographic attributes.

```APIDOC
## GET /api/search_geo/<input_search>

### Description
Search for subdivisions and return only geographic attributes (e.g. latLng, bounding box, geojson, neighbours, perimeter) for 1 or more input search terms.

### Method
GET

### Endpoint
/api/search_geo/<input_search>

### Parameters
#### Path Parameters
- **input_search** (string) - Required - Comma separated list of subdivision names or codes.

#### Query Parameters
- **likeness** (integer) - Optional - Likeness score between 1-100 to control match tolerance.
```

--------------------------------

### GET /api/subdivision/{code}

Source: https://iso3166-2.readthedocs.io/en/latest/api.html

Retrieves subdivision data for a specific subdivision using its official ISO 3166-2 code.

```APIDOC
## GET /api/subdivision/{code}

### Description
Get all subdivision data for a single or subset of subdivisions using their official ISO 3166-2 subdivision code.

### Method
GET

### Endpoint
https://iso3166-2-api.vercel.app/api/subdivision/{code}

### Parameters
#### Path Parameters
- **code** (string) - Required - The official ISO 3166-2 subdivision code (e.g., LV-007, PA-3, ZA-NC).
```

--------------------------------

### GET /api/country_name/{name}

Source: https://iso3166-2.readthedocs.io/en/latest/_sources/api.rst.txt

Retrieves all subdivision data for a country using its officially recognized English name.

```APIDOC
## GET /api/country_name/{name}

### Description
Get all subdivision data using the officially recognized country name, as it is commonly known in English.

### Method
GET

### Endpoint
/api/country_name/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - The English name of the country (e.g., Tajikistan).
```

--------------------------------

### GET /api/country_name/{name}

Source: https://iso3166-2.readthedocs.io/en/latest/api.html

Retrieves all subdivision data for a country using its officially recognized English name.

```APIDOC
## GET /api/country_name/{name}

### Description
Get all subdivision data using the officially recognized country name, as it is commonly known in English.

### Method
GET

### Endpoint
https://iso3166-2-api.vercel.app/api/country_name/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - The common English name of the country (e.g., Tajikistan, Seychelles, Uganda).
```

--------------------------------

### GET /api/alpha/{code}

Source: https://iso3166-2.readthedocs.io/en/latest/_sources/api.rst.txt

Retrieves subdivision data for a specific country using its ISO 3166-1 alpha-2, alpha-3, or numeric code.

```APIDOC
## GET /api/alpha/{code}

### Description
Access all subdivision data for a country via its alpha-2, alpha-3, or numeric country code.

### Method
GET

### Endpoint
/api/alpha/{code}

### Parameters
#### Path Parameters
- **code** (string) - Required - The ISO 3166-1 alpha-2, alpha-3, or numeric country code.

#### Query Parameters
- **filterAttributes** (string) - Optional - A subset of desired attributes per subdivision to include in the output.
```

--------------------------------

### GET /api/alpha/{code}

Source: https://iso3166-2.readthedocs.io/en/latest/api.html

Retrieves subdivision data for a specific country using its ISO 3166-1 alpha-2, alpha-3, or numeric code.

```APIDOC
## GET /api/alpha/{code}

### Description
Accesses all subdivision data for a specific country via its alpha-2, alpha-3, or numeric country code.

### Method
GET

### Endpoint
https://iso3166-2-api.vercel.app/api/alpha/{code}

### Parameters
#### Path Parameters
- **code** (string) - Required - The ISO 3166-1 country code (alpha-2, alpha-3, or numeric).
```

--------------------------------

### GET /api/subdivision/{code}

Source: https://iso3166-2.readthedocs.io/en/latest/_sources/api.rst.txt

Retrieves subdivision data for a single or subset of subdivisions using their official ISO 3166-2 subdivision code.

```APIDOC
## GET /api/subdivision/{code}

### Description
Get all subdivision data for a single or subset of subdivisions using their official ISO 3166-2 subdivision code.

### Method
GET

### Endpoint
/api/subdivision/{code}

### Parameters
#### Path Parameters
- **code** (string) - Required - The ISO 3166-2 subdivision code (e.g., LV-007).
```

--------------------------------

### GET /api/search_geo/{query}

Source: https://iso3166-2.readthedocs.io/en/latest/_sources/api.rst.txt

Search for a specific ISO 3166-2 subdivision and return geographic attributes.

```APIDOC
## GET /api/search_geo/{query}

### Description
Search for a specific ISO 3166-2 subdivision and return geographic attributes such as latLng, boundingBox, geojson, neighbours, and perimeter.

### Method
GET

### Endpoint
https://iso3166-2-api.vercel.app/api/search_geo/{query}

### Parameters
#### Path Parameters
- **query** (string) - Required - Comma separated list of subdivision names or ISO 3166-2 subdivision codes.
```

--------------------------------

### GET /api/list_subdivisions

Source: https://iso3166-2.readthedocs.io/en/latest/api.html

Retrieve a list of all ISO 3166-2 subdivision codes, optionally filtered by a specific ISO 3166-1 country code.

```APIDOC
## GET /api/list_subdivisions

### Description
Return a list of all ISO 3166-2 subdivision codes for each country. Optionally filter by appending the ISO 3166-1 country code.

### Method
GET

### Endpoint
/api/list_subdivisions or /api/list_subdivisions/{country_code}

### Parameters
#### Path Parameters
- **country_code** (string) - Optional - The ISO 3166-1 country code to filter the subdivision list.
```

--------------------------------

### GET /api/search/{term}

Source: https://iso3166-2.readthedocs.io/en/latest/_sources/api.rst.txt

Searches for subdivisions using a name or local/other names with optional likeness and exclusion parameters.

```APIDOC
## GET /api/search/{term}

### Description
Search for a specific subdivision using its subdivision name or local/other names. Results are sorted by matchScore.

### Method
GET

### Endpoint
/api/search/{term}

### Parameters
#### Path Parameters
- **term** (string) - Required - The search term for the subdivision name.

#### Query Parameters
- **likeness** (integer) - Optional - A value between 1-100 representing the percentage of likeness to the search term.
- **excludeMatchScore** (boolean) - Optional - If set, excludes the matchScore attribute and sorts results alphabetically.
```

--------------------------------

### GET /api/search/{search_term}

Source: https://iso3166-2.readthedocs.io/en/latest/api.html

Searches for subdivisions based on the provided name or local/other names. Supports fuzzy matching and sorting configuration.

```APIDOC
## GET /api/search/{search_term}

### Description
Searches for a specific subdivision using its name or local/other names. The results are sorted by a matchScore attribute by default.

### Method
GET

### Endpoint
/api/search/{search_term}

### Parameters
#### Path Parameters
- **search_term** (string) - Required - The name or identifier of the subdivision to search for.

#### Query Parameters
- **likeness** (integer) - Optional - A value between 1-100 representing the percentage of likeness for fuzzy matching. Defaults to 100.
- **excludeMatchScore** (integer) - Optional - If set to 1, excludes the matchScore attribute from the output and sorts results alphabetically.
```

--------------------------------

### GET /api/search_geo/{input_search}

Source: https://iso3166-2.readthedocs.io/en/latest/api.html

Search for a specific ISO 3166-2 subdivision and return geographic attributes like latLng, boundingBox, and geojson. Input is a comma-separated list of names or codes.

```APIDOC
## GET /api/search_geo/{input_search}

### Description
Search for a specific ISO 3166-2 subdivision and return geographic attributes (latLng, boundingBox, geojson, neighbours, perimeter). The search is approximate based on a likeness score.

### Method
GET

### Endpoint
/api/search_geo/{input_search}

### Parameters
#### Path Parameters
- **input_search** (string) - Required - Comma separated list of subdivision names or ISO 3166-2 subdivision codes.
```

--------------------------------

### Subdivisions.__init__

Source: https://iso3166-2.readthedocs.io/en/latest/_sources/usage.rst.txt

Initializes the Subdivisions class with optional attribute filtering.

```APIDOC
## Subdivisions(filter_attributes=None)

### Description
Creates an instance of the Subdivisions class. The filter_attributes parameter allows restricting the output to a subset of default attributes.

### Parameters
- **filter_attributes** (str) - Optional - Comma-separated list of attributes to include in the output.
```

--------------------------------

### Retrieve all subdivision data

Source: https://iso3166-2.readthedocs.io/en/latest/api.html

Fetches the complete dataset for all countries from the /api/all endpoint.

```python
import requests

base_url = "https://iso3166-2-api.vercel.app/api/"
all_data = requests.get(f'{base_url}all').json()

all_data["AD"] #subdivision data for Andorra
all_data["IE"] #subdivision data for Ireland
all_data["PW"] #subdivision data for Palau
all_data["ZA"] #subdivision data for South Africa
```

```bash
$ curl -i https://iso3166-2-api.vercel.app/api/all
```

--------------------------------

### Manage custom subdivisions in Python

Source: https://iso3166-2.readthedocs.io/en/latest/_sources/usage.rst.txt

Add or delete custom subdivisions in-memory or persist changes to disk. Use custom_attributes to include additional metadata like population or GDP.

```python
from iso3166_2 import *

#create instance of Subdivisions class
iso = Subdivisions()

#adding custom Belfast province to Ireland (IE) - in-memory only (default)
iso.custom_subdivision("IE", "IE-BF", name="Belfast", local_other_name="Béal Feirste", type_="province", lat_lng=[54.596, -5.931], parent_code=None, flag=None)

#adding custom Mariehamn province to Aland Islands (AX), saving to a new separate file
iso.custom_subdivision("AX", "AX-M", name="Mariehamn", local_other_name="Maarianhamina", type_="province", lat_lng=[60.0969, 19.934], parent_code=None, flag=None,
   save_new=True, save_new_filename="iso3166-2-AX-M.json")

#adding custom Alaska province to Russia and persisting the change to the installed data file
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={"gini": "0.43", "gdpPerCapita": "71,996"}, persist=True)

#deleting above custom subdivisions from object (in-memory only)
iso.custom_subdivision("IE", "IE-BF", delete=True)
iso.custom_subdivision("AX", "AX-M", delete=True)
#deleting the persisted subdivision and writing the removal back to the installed file
iso.custom_subdivision("RU", "RU-ASK", delete=True, persist=True)
```

--------------------------------

### Subdivisions.search()

Source: https://iso3166-2.readthedocs.io/en/latest/usage.html

Searches for subdivisions using a fuzzy matching algorithm based on name and optional local other names.

```APIDOC
## search(name, likeness=100, exclude_match_score=False, local_other_name_search=False, filter_attributes=None)

### Description
Searches for a specific subdivision via its name using a fuzzy search algorithm. Results can be filtered by likeness score, attribute inclusion, and search scope.

### Parameters
- **name** (string) - Required - The subdivision name to search for.
- **likeness** (int) - Optional - A value between 1 and 100 representing the required percentage match score. Defaults to 100.
- **exclude_match_score** (bool) - Optional - If set to True, excludes the Match Score attribute from the results. Defaults to False.
- **local_other_name_search** (bool) - Optional - If set to True, includes the localOtherName attribute in the search space. Defaults to False.
- **filter_attributes** (string) - Optional - A comma-separated list of specific data attributes to return in the results.

### Usage Example
```python
from iso3166_2 import Subdivisions
iso = Subdivisions()

# Search with likeness threshold and attribute filtering
iso.search("Southern", likeness=70, exclude_match_score=True)

# Search including local other names
iso.search("City", likeness=40, local_other_name_search=True)

# Search with specific attribute return filter
iso.search("Texas, Meuse", filter_attributes="name,type")
```
```

--------------------------------

### Retrieve subdivision data by code

Source: https://iso3166-2.readthedocs.io/en/latest/api.html

Fetches data for a specific subdivision using its official ISO 3166-2 code.

```python
import requests

base_url = "https://iso3166-2-api.vercel.app/api/"
input_subdivision = "LV-007" #PA-3, ZA-NC
all_data = requests.get(f'{base_url}/subdivision/{input_subdivision}').json()

all_data["LV-007"] #data for LV-007 subdivision
#all_data["PA-3"] #data for PA-3 subdivision
#all_data["ZA-NC"] #data for ZA-NC subdivision
```

```bash
$ curl -i https://iso3166-2-api.vercel.app/api/subdivision/LV-007
$ curl -i https://iso3166-2-api.vercel.app/api/subdivision/PA-3
$ curl -i https://iso3166-2-api.vercel.app/api/subdivision/ZA-NC
```

--------------------------------

### Reverse Lookup by Coordinates

Source: https://iso3166-2.readthedocs.io/en/latest/_sources/usage.rst.txt

Find nearby subdivisions based on latitude and longitude coordinates.

```python
from iso3166_2 import *

iso = Subdivisions()

#find subdivisions near Berlin within 25 km
iso.reverse_lookup(52.5174, 13.3951, radius_km=25, max_results=5, region="DE")

#return only selected attributes
iso.reverse_lookup(52.5174, 13.3951, filter_attribute="name,type,latLng")
```

--------------------------------

### Remove attributes from dataset in Python

Source: https://iso3166-2.readthedocs.io/en/latest/_sources/usage.rst.txt

Initialize the Subdivisions class to manage attribute removal from the dataset.

```python
from iso3166_2 import *

#create instance of Subdivisions class
iso = Subdivisions()
```

--------------------------------

### Access Danish subdivision data

Source: https://iso3166-2.readthedocs.io/en/latest/_sources/usage.rst.txt

Retrieve and inspect Danish subdivision data.

```python
iso["DNK"] 
#{'DK-81': {'name': 'Nordjylland', 'localOtherName': 'Nordjylland', 'type': 'Region', 'parentCode': None,...}

#DK-81 Nordjylland
dk_nordjylland = iso["DNK"]["DK-81"] #or iso["DK-81"]
dk_nordjylland.name #Nordjylland
dk_nordjylland.latLng #[56.831, 9.493]
dk_nordjylland.type #Region

#DK-84 Hovedstaden
dk_hovedstaden = iso["DNK"]["DK-84"] #or iso["DK-84"]
dk_hovedstaden.name #Hovedstaden
dk_hovedstaden.flag #https://raw.githubusercontent.com/amckenna41/iso3166-flags/main/iso3166-2-icons/DK/DK-84.svg
dk_hovedstaden.parentCode #null

#DK-85 Sjælland
dk_sjalland = iso["DK"]["DNK-85"] #or iso["DK-85"]
dk_sjalland.name #Sjælland
dk_sjalland.type #Region
dk_sjalland.flag #https://raw.githubusercontent.com/amckenna41/iso3166-flags/main/iso3166-2-icons/DK/DK-85.svg
```

--------------------------------

### Filter subdivision attributes in Python

Source: https://iso3166-2.readthedocs.io/en/latest/_sources/usage.rst.txt

Initialize the Subdivisions class with a comma-separated list of attributes to restrict the output data.

```python
from iso3166_2 import *

#crete instance of Subdivisions class, filtering out all attributes but flag and type from subdivisions
iso = Subdivisions(filter_attributes="flag,type")

#crete instance of Subdivisions class, filtering out all attributes but name and flag from subdivisions
iso = Subdivisions(filter_attributes="name,flag")

#crete instance of Subdivisions class, filtering out all attributes but name,localOtherName,parentCode,type,flag from subdivisions
iso = Subdivisions(filter_attributes="name,localOtherName,parentCode,type,flag")
```

--------------------------------

### Search with likeness parameter

Source: https://iso3166-2.readthedocs.io/en/latest/api.html

Adjust the fuzzy matching threshold using the likeness query parameter (1-100).

```python
import requests

base_url = "https://iso3166-2-api.vercel.app/api/"
input_search = "Northern" #Southern
all_data = requests.get(f'{base_url}/search/{input_search}', params={"likeness": 80).json()
```

```bash
$ curl -i https://iso3166-2-api.vercel.app/api/search/Northern?likeness=80
$ curl -i https://iso3166-2-api.vercel.app/api/search/Southern?likeness=80
```

--------------------------------

### Handle invalid subdivision codes

Source: https://iso3166-2.readthedocs.io/en/latest/troubleshooting.html

Demonstrates how the package raises a SubdivisionNotFound error when an invalid code is provided.

```python
from iso3166_2 import Subdivisions

iso = Subdivisions()
iso["DE-BER"]  # raises SubdivisionNotFound with "Did you mean..."
```

--------------------------------

### Extract subdivision codes

Source: https://iso3166-2.readthedocs.io/en/latest/_sources/usage.rst.txt

Retrieve lists of subdivision codes for all countries or specific countries.

```python
from iso3166_2 import *

#crete instance of Subdivisions class
iso = Subdivisions()

iso.subdivision_codes()
```

```python
iso.subdivision_codes("NG")
```

--------------------------------

### Extract Subdivision Names

Source: https://iso3166-2.readthedocs.io/en/latest/_sources/usage.rst.txt

Retrieve lists of subdivision names for all countries or specific subsets.

```python
from iso3166_2 import *

#crete instance of Subdivisions class
iso = Subdivisions()

iso.subdivision_names()
```

```python
iso.subdivision_names("CU")
```

```python
iso.subdivision_names("FRA")
```

```python
iso.subdivision_names("GE, GIN, 404")
```

```python
iso["BA"].subdivision_names()
iso["MI"].subdivision_names()
```

--------------------------------

### Retrieve subdivision data by country name

Source: https://iso3166-2.readthedocs.io/en/latest/api.html

Fetches subdivision data for a country using its common English name.

```python
import requests

base_url = "https://iso3166-2-api.vercel.app/api/"
input_country_name = "Tajikistan" #Seychelles, Uganda
all_data = requests.get(f'{base_url}/country_name/{input_country_name}').json()

all_data["TJ"] #subdivision data for Tajikistan
#all_data["SC"] #subdivision data for Seychelles
#all_data["UG"] #subdivision data for Uganda
```

```bash
$ curl -i https://iso3166-2-api.vercel.app/api/country_name/Tajikistan
$ curl -i https://iso3166-2-api.vercel.app/api/country_name/Seychelles
$ curl -i https://iso3166-2-api.vercel.app/api/country_name/Uganda
```

--------------------------------

### Tune search relevance

Source: https://iso3166-2.readthedocs.io/en/latest/troubleshooting.html

Use filters and likeness scores to refine search results.

```python
iso.search(
    "Berlin",
    likeness_score=90,
    subdivision_type="Land",
    region="DE",
    exclude_match_score=False,
)
```

--------------------------------

### len(Subdivisions)

Source: https://iso3166-2.readthedocs.io/en/latest/_sources/usage.rst.txt

Returns the total number of subdivision objects in the dataset.

```APIDOC
## len(iso)

### Description
Returns the total count of individual ISO 3166-2 subdivision objects currently loaded in the instance.
```

--------------------------------

### Search for specific subdivisions

Source: https://iso3166-2.readthedocs.io/en/latest/api.html

Retrieve data for multiple subdivisions by providing a comma-separated list of names.

```python
import requests

base_url = "https://iso3166-2-api.vercel.app/api/"
input_search = "Saarland, Brokopondo, Delaware" #DE-SL, SR-BR, US-DE
all_data = requests.get(f'{base_url}/search/{input_search}').json()

all_data["DE-SL"] #subdivision data for Saarland
all_data["SR-BR"] #subdivision data for Brokopondo
all_data["US-DE"] #subdivision data for Delaware
```

```bash
$ curl -i https://iso3166-2-api.vercel.app/api/search/Saarland
$ curl -i https://iso3166-2-api.vercel.app/api/search/Brokopondo
$ curl -i https://iso3166-2-api.vercel.app/api/search/Delaware
$ curl -i https://iso3166-2-api.vercel.app/api/search/Saarland,Brokopondo,Delaware
```

--------------------------------

### Access Estonian subdivision data

Source: https://iso3166-2.readthedocs.io/en/latest/_sources/usage.rst.txt

Retrieve and inspect Estonian subdivision data.

```python
iso["233"]
#{'EE-37': {'name': 'Harjumaa', 'localOtherName': 'Harjumaa', 'type': 'County', 'parentCode': None,...}

#EE-39 Hiiumaa
ee_hiiumaa = iso["233"]["EE-39"] #or iso["EE-39"]
ee_hiiumaa.name #Hiiumaa
ee_hiiumaa.localOtherName #Hiiumaa
ee_hiiumaa.latLng #[58.924, 22.592]

#EE-130 Alutaguse
ee_alutaguse = iso["233"]["EE-130"] #or iso["EE-130"]
ee_alutaguse.name #Alutaguse
ee_alutaguse.parentCode #EE-45
ee_alutaguse.flag #https://raw.githubusercontent.com/amckenna41/iso3166-flags/main/iso3166-2-icons/EE/EE-130.svg

#EE-338 Kose
ee_kose = iso["233"]["EE-338"] #or iso["EE-338"]
ee_kose.name #Kose
ee_kose.type #Rural municipality
ee_kose.parentCode #EE-37
```

--------------------------------

### Retrieve subdivision data by numeric code

Source: https://iso3166-2.readthedocs.io/en/latest/api.html

Access subdivision data for a specific country using its numeric ISO 3166-1 code.

```python
import requests

base_url = "https://iso3166-2-api.vercel.app/api/"
input_alpha = "558" #598, 634 (NI, PG, QA)
all_data = requests.get(f'{base_url}/alpha/{input_alpha}').json()

all_data["NI"] #subdivision data for Nicaragua
#all_data["PG"] #subdivision data for Papua New Guinea
#all_data["QA"] #subdivision data for Qatar
```

```bash
$ curl -i https://iso3166-2-api.vercel.app/api/alpha/558
$ curl -i https://iso3166-2-api.vercel.app/api/alpha/598
$ curl -i https://iso3166-2-api.vercel.app/api/alpha/634
```

--------------------------------

### Subdivisions.reverse_lookup(lat, lng, **kwargs)

Source: https://iso3166-2.readthedocs.io/en/latest/_sources/usage.rst.txt

Finds nearby subdivisions based on latitude and longitude coordinates.

```APIDOC
### Method
`iso.reverse_lookup(lat, lng, radius_km=None, max_results=None, region=None, filter_attribute=None)`

### Parameters
- **lat** (float) - Required - Latitude.
- **lng** (float) - Required - Longitude.
- **radius_km** (int) - Optional - Search radius in kilometers.
- **max_results** (int) - Optional - Maximum number of results to return.
- **region** (string) - Optional - Filter by region code.
- **filter_attribute** (string) - Optional - Attributes to return.
```

--------------------------------

### Subdivisions.search(query, **kwargs)

Source: https://iso3166-2.readthedocs.io/en/latest/_sources/usage.rst.txt

Performs a fuzzy search for subdivisions based on name, with options for likeness scoring, attribute filtering, and regional constraints.

```APIDOC
### Method
`iso.search(query, likeness=None, exclude_match_score=None, local_other_name_search=None, filter_attributes=None, subdivision_type=None, region=None, parent_code=None)`

### Parameters
- **query** (string) - Required - The search term.
- **likeness** (int) - Optional - Percentage likeness score (1-100).
- **exclude_match_score** (bool/int) - Optional - Whether to exclude the match score from results.
- **local_other_name_search** (bool) - Optional - Whether to include localOtherName in search.
- **filter_attributes** (string) - Optional - Comma-separated list of attributes to return.
- **subdivision_type** (string) - Optional - Filter by subdivision type.
- **region** (string) - Optional - Filter by region code.
- **parent_code** (string) - Optional - Filter by parent subdivision code.
```

--------------------------------

### Subdivisions.subdivision_names(country_code=None)

Source: https://iso3166-2.readthedocs.io/en/latest/_sources/usage.rst.txt

Retrieves a list of subdivision names for all countries or a specific subset.

```APIDOC
### Method
`iso.subdivision_names(country_code=None)`

### Parameters
- **country_code** (string) - Optional - The alpha code(s) of the country to filter by.
```

--------------------------------

### Subdivisions.subdivision_codes

Source: https://iso3166-2.readthedocs.io/en/latest/usage.html

Retrieves a list of subdivision codes for all countries or specific countries provided as an argument.

```APIDOC
## Method: subdivision_codes(country_codes=None)

### Description
Returns the full list of subdivision codes. If country_codes is provided, it filters the results for the specified countries.

### Parameters
- **country_codes** (string) - Optional - A comma-separated string of country alpha-2, alpha-3, or numeric codes.

### Example
```python
from iso3166_2 import Subdivisions
iso = Subdivisions()
# Get all
iso.subdivision_codes()
# Get specific
iso.subdivision_codes("NG")
iso.subdivision_codes("SG, SOM, 768")
```
```

--------------------------------

### Search for Subdivisions

Source: https://iso3166-2.readthedocs.io/en/latest/_sources/usage.rst.txt

Perform fuzzy searches for subdivisions using names, likeness scores, and optional attribute filtering.

```python
from iso3166_2 import *

#crete 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")

#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 70, exclude Match Score attribute
iso.search("Southern", likeness=70, exclude_match_score=1)

#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")
```

--------------------------------

### Access Canadian subdivision data

Source: https://iso3166-2.readthedocs.io/en/latest/_sources/usage.rst.txt

Retrieve and inspect Canadian subdivision data using the Subdivisions instance.

```python
from iso3166_2 import *

#crete instance of Subdivisions class
iso = Subdivisions()

iso["CA"] 
#{'CA-AB': {'name': 'Alberta', 'localOtherName': 'Alberta', 'type': 'Province', 'parentCode': None,...}

#CA-AB Alberta
ca_alberta = iso["CA"]["CA-AB"] #or iso["CA-AB"]
ca_alberta.name #Alberta
ca_alberta.type #Province
ca_alberta.flag #https://raw.githubusercontent.com/amckenna41/iso3166-flags/main/iso3166-2-icons/CA/CA-AB.svg

#CA-MB Manitoba
ca_manitoba = iso["CA"]["CA-MB"] #or iso["CA-MB"]
ca_manitoba.name #Manitoba
ca_manitoba.parentCode #null
ca_manitoba.localOtherName #Manitoba

#CA-NS Nova Scotia
ca_nova_scotia = iso["CA"]["CA-NS"] #or iso["CA-NS"]
ca_nova_scotia.name #Nova Scotia
ca_nova_scotia.flag #https://github.com/amckenna41/iso3166-flags/blob/main/iso3166-2-icons/CA/CA-NS.svg
ca_nova_scotia.history #None
```

--------------------------------

### Perform reverse coordinate lookup

Source: https://iso3166-2.readthedocs.io/en/latest/troubleshooting.html

Search for subdivisions within a specific radius of given coordinates.

```python
iso.reverse_lookup(52.5174, 13.3951, radius_km=75, region="DE")
```

--------------------------------

### Count subdivision objects in Python

Source: https://iso3166-2.readthedocs.io/en/latest/_sources/usage.rst.txt

Use the built-in len() function to retrieve the total count of subdivision objects.

```python
from iso3166_2 import *

#create instance of Subdivisions class
iso = Subdivisions()

#get total number of subdivision objects via len() - 5,046
len(iso)
```

--------------------------------

### Extract Subdivision Codes

Source: https://iso3166-2.readthedocs.io/en/latest/_sources/usage.rst.txt

Retrieve subdivision codes using country alpha codes or numeric identifiers.

```python
iso.subdivision_codes("SAU")
```

```python
iso.subdivision_codes("SG, SOM, 768")
```

```python
iso["AL"].subdivision_names()
iso["ET"].subdivision_names()
```

--------------------------------

### Retrieve subdivision data by alpha-2 code

Source: https://iso3166-2.readthedocs.io/en/latest/api.html

Access subdivision data for a specific country using its two-letter ISO 3166-1 code.

```python
import requests

base_url = "https://iso3166-2-api.vercel.app/api/"
input_alpha = "FR" #DE, GM
all_data = requests.get(f'{base_url}/alpha/{input_alpha}').json()

all_data["FR"] #subdivision data for France
#all_data["DE"] #subdivision data for Germany
#all_data["GM"] #subdivision data for Gambia
```

```bash
$ curl -i https://iso3166-2-api.vercel.app/api/alpha/FR
$ curl -i https://iso3166-2-api.vercel.app/api/alpha/DE
$ curl -i https://iso3166-2-api.vercel.app/api/alpha/GM
```

--------------------------------

### Retrieve subdivision data by alpha-3 code

Source: https://iso3166-2.readthedocs.io/en/latest/api.html

Access subdivision data for a specific country using its three-letter ISO 3166-1 code.

```python
import requests

base_url = "https://iso3166-2-api.vercel.app/api/"
input_alpha = "GRC" #MEX, MNE
all_data = requests.get(f'{base_url}/alpha/{input_alpha}').json()

all_data["GR"] #subdivision data for Greece
#all_data["MX"] #subdivision data for Mexico
#all_data["ME"] #subdivision data for Montenegro
```

```bash
$ curl -i https://iso3166-2-api.vercel.app/api/alpha/GRC
$ curl -i https://iso3166-2-api.vercel.app/api/alpha/MEX
$ curl -i https://iso3166-2-api.vercel.app/api/alpha/MNE
```

--------------------------------

### Subdivisions.subdivision_codes(country_code)

Source: https://iso3166-2.readthedocs.io/en/latest/_sources/usage.rst.txt

Retrieves a list of subdivision codes for a specified country or set of countries.

```APIDOC
### Method
`iso.subdivision_codes(country_code)`

### Parameters
- **country_code** (string) - Required - The alpha code(s) of the country (e.g., 'SAU', 'SG, SOM, 768').
```

--------------------------------

### Subdivisions.custom_subdivision

Source: https://iso3166-2.readthedocs.io/en/latest/_sources/usage.rst.txt

Adds or deletes a custom subdivision to the iso3166-2 dataset. Changes are in-memory by default but can be persisted to disk.

```APIDOC
## Subdivisions.custom_subdivision(country_code, subdivision_code, ...)

### Description
Adds or deletes a custom subdivision to an existing country. If the code exists, an error is raised; otherwise, it is appended.

### Parameters
- **country_code** (str) - Required - The ISO 3166-1 alpha-2 country code.
- **subdivision_code** (str) - Required - The custom subdivision code.
- **name** (str) - Optional - Name of the subdivision.
- **local_other_name** (str) - Optional - Local name of the subdivision.
- **type_** (str) - Optional - Type of subdivision (e.g., province).
- **lat_lng** (list) - Optional - Latitude and longitude coordinates.
- **parent_code** (str) - Optional - Parent subdivision code.
- **flag** (str) - Optional - Flag identifier.
- **custom_attributes** (dict) - Optional - Additional attributes like population or GDP.
- **delete** (bool) - Optional - If True, deletes the specified subdivision.
- **persist** (bool) - Optional - If True, overwrites the installed package's JSON file.
- **save_new** (bool) - Optional - If True, saves to a new file.
- **save_new_filename** (str) - Optional - Filename for the new dataset.
```

--------------------------------

### Advanced Search Filters

Source: https://iso3166-2.readthedocs.io/en/latest/_sources/usage.rst.txt

Apply targeted filters such as region, subdivision type, and parent codes to search queries.

```python
from iso3166_2 import *

iso = Subdivisions()

#ranked search constrained to one region and type
iso.search(
   "Berlin",
   likeness_score=90,
   subdivision_type="Land",
   region="DE",
   exclude_match_score=False,
)

#filter by parent code
iso.search("Armagh", parent_code="GB-NIR", region="GB")
```

--------------------------------

### Search with excluded match score

Source: https://iso3166-2.readthedocs.io/en/latest/_sources/api.rst.txt

Perform a search while excluding the match score attribute from the output.

```python
import requests
```

--------------------------------

### Remove subdivision attributes

Source: https://iso3166-2.readthedocs.io/en/latest/_sources/usage.rst.txt

Removes specified attributes from the subdivision data. Use the overwrite_data parameter with caution as it permanently modifies the source JSON file.

```python
#remove the flag attribute from all subdivisions
iso.remove_attributes(["flag"])

#remove the history attribute and overwrite the original JSON file
iso.remove_attributes(["history"], overwrite_data=True)
```