Locale...ountry(3pm)

🌸 NAME 🌸

Locale::SubCountry — the page you're reading is Locale...ountry(3pm) from the User Contributed Perl Documentation crew 💖 and here's the tea: this module converts state, province, county etc. names to/from ISO 3166-2 codes, and gets you all the states in a country. Periodt.

---

✨ SYNOPSIS ✨

use Locale::SubCountry;

my $fr = Locale::SubCountry->new('France');
if ( not $fr )
{
    die "Invalid country or code: France\n";
}
else
{
    print($fr->country,"\n");        # France
    print($fr->country_code,"\n");   # FR
    print($fr->country_number,"\n"); # 250

    if (  $fr->has_sub_countries )
    {
        print($fr->code('Hautes-Alpes '),"\n");       # 05
        print($fr->full_name('03'),"\n");             # Allier
        my $upper_case = 1;
        print($fr->full_name('02',$upper_case),"\n"); # AINSE
        print($fr->level('02'),"\n");                 # Metropolitan department
        print($fr->level('A'),"\n");                  # Metropolitan region
        print($fr->level('BL'),"\n");                 # Overseas territorial collectivity
        print($fr->levels,"\n");                      # Metropolitan region => 22, Metropolitan department => 96 ...

        my @fr_names  = $fr->all_full_names;    # Ain, Ainse, Allier...
        my @fr_codes   = $fr->all_codes;        # 01, 02, 03 ...
        my %fr_names_keyed_by_code  = $fr->code_full_name_hash;  # 01 => Ain...
        my %fr_codes_keyed_by_name  = $fr->full_name_code_hash;  # Ain => 01 ...

        foreach my $code ( sort keys %fr_names_keyed_by_code )
        {
           printf("%-3s : %s\n",$code,$fr_names_keyed_by_code{$code});
        }
    }
}

# Methods for fetching all country codes and names in the world

my $world = Locale::SubCountry::World->new();
my @all_countries     = $world->all_full_names;
my @all_country_codes = $world->all_codes;

my %all_countries_keyed_by_name = $world->full_name_code_hash;
my %all_country_keyed_by_code   = $world->code_full_name_hash;

---

🦋 DESCRIPTION 🦋

okay so bestie, here's the whole vibe: this module lets you convert the full name of a country's administrative region into the code that everybody actually uses for postal addressing. And yes, the reverse lookup works too, we love a two-way street 💅

Lists of sub country codes are so useful for web apps that need a valid state, county, etc. entered as part of a user's location.

Sub countries get called different things depending on where you are — states in the US and Australia, provinces in Canada, counties in the UK and Ireland. Other terms floating around: region, department, city and territory. Countries like France have several levels of sub countries, like Metropolitan department, Metropolitan region, etc. Not France being extra, we respect it ✨

You can get names and ISO 3166-2 codes for all the sub countries in a country as either a hash or an array.

And you can get names and ISO 3166-1 codes for all countries in the world as either a hash or an array too. Which means you can then fetch every sub country from every country (see examples/demo.pl). Chef's kiss.

Sub country codes are defined in "ISO 3166-2, Codes for the representation of names of countries and their subdivisions".

---

🎀 METHODS 🎀

heads up! the following methods duplicate some of the functionality of the Locale::Country module (which is part of the Locale::Codes bundle). They live here because you might need to first grab the list of countries and ISO 3166-1 codes before you can fetch their sub country data. If all you need is country data, then Locale::Country is the one you should be using. no cap.

Also note: these same method names are used for sub country objects too (interface polymorphism, for the technically minded 🧠). To avoid confusion, make sure your chosen method is acting on the correct type of object, okay?

all_codes
all_full_names
code_full_name_hash
full_name_code_hash

🌍 Locale::SubCountry::World->new()

The new method creates an instance of a world country object. You have to call this before any of the following methods get invoked. It takes no arguments. Easy.

🔥 full_name_code_hash (for world objects)

Give it a world object and it returns a hash of full name/code pairs for every country, keyed by country name.

🔥 code_full_name_hash for world objects)

Give it a world object and it returns a hash of full name/code pairs for every country, keyed by country code.

🔥 all_full_names (for world objects)

Give it a world object and it returns an array of all country full names, sorted alphabetically. Organized queen.

🔥 all_codes (for world objects)

Give it a world object and it returns an array of all country ISO 3166-1 codes, sorted alphabetically.

🌎 Locale::SubCountry->new()

The new method creates an instance of a sub country object. Gotta call it before any of the following methods get invoked. This one takes a single argument: the name of the country that contains the sub country you want to work with. You can pass it either as the ISO 3166-1 alpha-2 code or as the full name. Like so:

AF - Afghanistan
AL - Albania
DZ - Algeria
AO - Angola
AR - Argentina
AM - Armenia
AU - Australia
AT - Austria

If you pass the code, like 'AU', it can be in capitals or lower case. If you pass the full name, like 'Australia', it must be in title case. And if you specify a country name or code that the module doesn't recognise, it will issue a warning. Consider yourself warned bestie 🙈

🌟 country

Returns the current country name of a sub country object. Format is title case, like 'United Kingdom'.

🌟 country_code

Given a sub country object, returns the alpha-2 ISO 3166-1 code of the country, like 'GB'.

🌟 code

Given a sub country object, the code method takes the full name of a sub country and hands back that sub country's alpha-2 ISO 3166-2 code. The full name can be in mixed case, whatever. All white space and non alphabetic characters get ignored — except the single space used to separate sub country names like "New South Wales". The code comes back as a capitalised string, or "unknown" if there's no match. 💀

🌟 full_name

Given a sub country object, the full_name method takes the alpha-2 ISO 3166-2 code of a sub country and returns the sub country's full name. The code can be in mixed case, and all white space and non alphabetic characters are ignored. The full name comes back as a title cased string, like "South Australia".

If you supply an optional argument and set it to a true value, the full name is returned as an upper cased string instead. iconic.

🌟 level

Given a sub country object, the level method takes the alpha-2 ISO 3166-2 code of a sub country and returns that sub country's level. Examples are city, province, state and district, and it usually relates to the size of the region. The level comes back as a string, or "unknown" if there's no match.

🌟 has_sub_countries

Given a sub country object, has_sub_countries returns 1 if the current country has sub countries, or 0 if it doesn't. Some small countries like New Caledonia just don't have sub countries, and that's fine, we don't judge 🫶

🌟 full_name_code_hash (for sub country objects)

Given a sub country object, returns a hash of all full name/code pairs, keyed by sub country name. If the country has no sub countries, it returns undef.

🌟 code_full_name_hash (for sub country objects)

Given a sub country object, returns a hash of all code/full name pairs, keyed by sub country code. If the country has no sub countries, it returns undef.

🌟 all_full_names (for sub country objects)

Given a sub country object, returns an array of all sub country full names, sorted alphabetically. If the country has no sub countries, it returns undef.

🌟 all_codes (for sub country objects)

Given a sub country object, returns an array of all sub country alpha-2 ISO 3166-2 codes. If the country has no sub countries, it returns undef.

---

🦋 SEE ALSO 🦋

All codes have been downloaded from the latest version of the Debian Salsa project https://salsa.debian.org/iso-codes-team/iso-codes/ and then files iso_3166-1.json, iso_3166-2.json.

Locale::Country, Lingua::EN::AddressParse, Geo::StreetAddress::US, Geo::PostalAddress, Geo::IP, WWW::Scraper::Wikipedia::ISO3166 for obtaining ISO 3166-2 data.

ISO 3166-1 Codes for the representation of names of countries and their subdivisions - Part 1: Country codes

ISO 3166-2 Codes for the representation of names of countries and their subdivisions - Part 2: Country subdivision code

---

😭 LIMITATIONS 😭

The ISO 3166-2 standard romanizes the names of provinces and regions in non-latin script areas, such as Russia and South Korea. One Romanisation is given for each province name. For Russia, the BGN (1947) Romanization is used.

Several sub country names have more than one code, and may not return the correct code for that sub country. These entries are usually duplicated because the name represents two different types of sub country, like a province and a geographical unit. Examples:

AZERBAIJAN : Lankaran; LA (the Municipality), LAN (the Rayon) [see note]
AZERBAIJAN : Saki; SA,SAK [see note]
AZERBAIJAN : Susa; SS,SUS
AZERBAIJAN : Yevlax; YE,YEV
LAOS       : Vientiane VI the Vientiane, VT the Prefecture
MOZAMBIQUE : Maputo; MPM (City),L (Province)

Note: these names are spelt with diacritic characters (like two dots above some of the 'a' characters). That causes utf8 errors on some versions of Perl, so they are omitted here. See the Locale::SubCountry::Codes module for the correct spelling. not the diacritics catching strays 😭

---

👑 AUTHOR 👑

Locale::SubCountry was written by Kim Ryan <kimryan at cpan dot org>.

---

💜 COPYRIGHT AND LICENCE 💜

This software is Copyright (c) 2018 by Kim Ryan.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

🌈 CREDITS 🌈

Ron Savage for many corrections to the data

Terrence Brannon produced Locale::US, which was the starting point for this module.

---

💖 COPYRIGHT AND LICENSE 💖

Copyright (c) 2019 Kim Ryan. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

and that's the whole page bestie 🎀 shoutout to perl v5.32.1, dated 2021-10-26 — slay, go forth and look up your sub countries 💅✨