NAME

Locale::SubCountry - convert state, province, county etc. names to/from code

SYNOPSIS

use Locale::SubCountry;

$UK_counties = new Locale::SubCountry('GB');
print($UK_counties->full_name('DUMGAL'));  # Dumfries & Galloway

$UK_counties = new Locale::SubCountry('AUSTRALIA');

print($australia->code('New South Wales '),"\n");     # NSW
print($australia->full_name('S.A.'),"\n");            # South Australia
$upper_case = 1;
print($australia->full_name('Qld',$upper_case),"\n"); # QUEENSLAND
print($australia->country,"\n");                      # AUSTRALIA
print($australia->country_code,"\n");                 # AU
print($australia->sub_country_type,"\n");             # State
print($australia->FIPS10_4_code('ACT'),"\n");         # 01
print($australia->ISO3166_2_code('02'),"\n");         # NSW


@aus_state_names  = $australia->all_full_names;
@aus_code_names   = $australia->all_codes;
%aus_states_keyed_by_code  = $australia->code_full_name_hash;
%aus_states_keyed_by_name  = $australia->full_name_code_hash;

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


# Methods for country codes and names

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

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

REQUIRES

Perl 5.005 or above

DESCRIPTION

This module allows you to convert the full name for a countries administrative region to the code commonly used for postal addressing. The reverse lookup can also be done. Sub country codes are defined in "ISO 3166-2:1998, Codes for the representation of names of countries and their subdivisions".

Sub countries are termed as states in the US and Australia, provinces in Canada and counties in the UK and Ireland.

Names and ISO 3166-2 codes for all sub countries in a country can be returned as either a hash or an array.

Names and ISO 3166-1 codes for all countries in the world can be returned as either a hash or an array.

ISO 3166-2 codes can be converted to FIPS 10 -4 codes. The reverse lookup can also be done.

METHODS

Note that the following methods duplicate some of the functionality of the Locale::Country module (part of the Locale::Codes bundle). They are provided here because you may need to first access the list of available countries and ISO 3166-1 codes, before fetching their sub country data. If you only need access to country data, then Locale::Country should be used.

Note also the following method names are also used for sub country objects. (interface polymorphism for the technically minded). To avoid confusion, make sure that your chosen method is acting on the correct type of object.

all_codes
all_full_names
code_full_name_hash
full_name_code_hash

new Locale::SubCountry::World

The new method creates an instance of a world country object. This must be called before any of the following methods are invoked. The method takes no arguments.

full_name_code_hash (for world objects)

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

code_full_name_hash for world objects)

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

all_full_names (for world objects)

Given a world object, returns an array of all country full names, sorted alphabetically.

all_codes (for world objects)

Given a world object, returns an array of all country IS) 3166-1 codes, sorted alphabetically.

new Locale::SubCountry

The new method creates an instance of a sub country object. This must be called before any of the following methods are invoked. The method takes a single argument, the name of the country that contains the sub country that you want to work with. It may be specified either by the ISO 3166-1 two letter code or the full name. These are currently:

AF - AFGHANISTAN
AL - ALBANIA
DZ - ALGERIA
AO - ANGOLA
AR - ARGENTINA
AM - ARMENIA
AU - AUSTRALIA
AT - AUSTRIA
AZ - AZERBAIJAN
BS - BAHAMAS
BH - BAHRAIN
BD - BANGLADESH
BY - BELARUS
BE - BELGIUM
BZ - BELIZE
BJ - BENIN
BT - BHUTAN
BO - BOLIVIA
BA - BOSNIA AND HERZEGOVINA
BW - BOTSWANA
BR - BRAZIL
BN - BRUNEI DARUSSALAM
BG - BULGARIA
BF - BURKINA FASO
KH - CAMBODIA
CM - CAMEROON
CA - CANADA
CV - CAPE VERDE
CF - CENTRAL AFRICAN REPUBLIC
TD - CHAD
CL - CHILE
CN - CHINA
CO - COLOMBIA
KM - COMOROS
CG - CONGO
CR - COSTA RICA
CI - CÔTE D'IVOIRE
HR - CROATIA
CU - CUBA
CY - CYPRUS
CX - CZECH REPUBLIC
CO - CONGO, THE DEMOCRATIC REPUBLIC OF THE CONGO
DK - DENMARK
DJ - DJIBOUTI
DO - DOMINICAN REPUBLIC
EC - ECUADOR
EG - EGYPT
SV - EL SALVADOR
QQ - EQUATORIAL GUINEA
ER - ERITREA
EE - ESTONIA
ET - ETHIOPIA
FJ - FIJI
FI - FINLAND
FR - FRANCE
GA - GABON
GM - GAMBIA
GE - GEORGIA
DE - GERMANY
GH - GHANA
GR - GREECE
GT - GUATEMALA
GN - GUINEA
GW - GUINEA BISSAU
GY - GUYANA
HT - HAITI
HN - HONDURAS
HU - HUNGARY
IE - ICELAND
IN - INDIA
ID - INDONESIA
IL - ISRAEL
IR - IRAN (ISLAMIC REPUBLIC OF)
IQ - IRAQ
IE - IRELAND
IT - ITALY
JM - JAMAICA
JP - JAPAN
JO - JORDAN
KZ - KAZAKHSTAN
KE - KENYA
KI - KIRIBATI
KP - KOREA, DEMOCRATIC PEOPLE'S REPUBLIC OF
KR - KOREA, REPUBLIC OF
KW - KUWAIT
KG - KYRGYZSTAN
LA - LAO PEOPLE'S DEMOCRATIC REPUBLIC
LV - LATVIA
LB - LEBANON
LS - LESOTHO
LR - LIBERIA
LY - LIBYAN ARAB JAMAHIRIYA
LT - LITHUANIA
MG - MADAGASCAR
MW - MALAWI
MY - MALAYSIA
MV - MALDIVES
ML - MALI
MH - MARSHALL ISLANDS
MR - MAURITANIA
MU - MAURITIUS
MX - MEXICO
FM - MICRONESIA (FEDERATED STATES OF)
MD - MOLDOVA, REPUPLIC OF
MN - MONGOLIA
MA - MOROCCO
MZ - MOZAMBIQUE
MM - MYANMAR
NA - NAMIBIA
NL - NETHERLANDS
NZ - NEW ZEALAND
NI - NICARAGUA
NE - NIGER
NG - NIGERIA
NO - NORWAY
OM - OMAN
PK - PAKISTAN
PA - PANAMA
PG - PAPUA NEW GUINEA
PY - PARAGUAY
PE - PERU
PH - PHILIPPINES
PL - POLAND
PT - PORTUGAL
QA - QATAR
RO - ROMANIA
RU - RUSSIA
RW - RWANDA
ST - SAO TOME AND PRINCIPE
SA - SAUDI ARABIA
SN - SENEGAL
SL - SIERRA LEONE
SG - SINGAPORE
SK - SLOVAKIA
SI - SLOVENIA
SB - SOLOMON ISLANDS
SO - SOMALIA
ZA - SOUTH AFRICA
ES - SPAIN
LK - SRI LANKA
SH - ST HELENA
SD - SUDAN
SR - SURINAME
SZ - SWAZILAND
SE - SWEDEN
CH - SWITZERLAND
SY - SYRIAN ARAB REPUBLIC
TW - TAIWAN, PROVINCE OF CHINA
TJ - TAJIKISTAN
TZ - TANZANIA, UNITED REPUBLIC OF
TH - THAILAND
TG - TOGO
TL - TIMOR-LESTE
TT - TRINIDAD AND TOBAGO
TN - TUNISIA
TR - TURKEY
TM - TURKMENISTAN
UG - UGANDA
UA - UKRAINE
AE - UNITED ARAB EMIRATES
GB - UNITED KINGDOM
US - UNITED STATES
UM - UNITED STATES MINOR OUTLYING ISLANDS
UY - URUGUAY
UZ - UZBEKISTAN
VU - VANUATU
VE - VENEZUELA
VN - VIET NAM
WF - WALLIS AND FUTUNA ISLANDS
YE - YEMEN
YU - YUGOSLAVIA
ZM - ZAMBIA
ZW - ZIMBABWE

All forms of upper/lower case are acceptable in the country's spelling. If a country name is supplied that the module doesn't recognised, it will die.

country

Returns the current country of a sub country object

country_code

Given a sub country object, returns the two letter ISO 3166-1 code of the country

sub_country_type

Given a sub country object, returns the sub country type (state, county etc), or 'unknown' if a value is not defined.

code

Given a sub country object, the code method takes the full name of a sub country and returns the sub country's ISO 3166-2 code. The full name can appear in mixed case. All white space and non alphabetic characters are ignored, except the single space used to separate sub country names such as "New South Wales". The code is returned as a capitalised string, or "unknown" if no match is found.

full_name

Given a sub country object, the full_name method takes the ISO 3166-2 code of a sub country and returns the sub country's full name. The code can appear in mixed case. All white space and non alphabetic characters are ignored. The full name is returned as a title cased string, such as "South Australia".

If an optional argument is supplied and set to a true value, the full name is returned as an upper cased string.

FIPS10_4_code

Given a sub country object, the FIPS_10_4_code method takes the ISO 3166-2 code of a sub country and returns the sub country's FIPS 10-4 code. FIPS is a standard developed by the US government.

ISO3166_2_code

Given a sub country object, the ISO3166_2_code method takes the FIPS 10-4 code of a sub country and returns the sub country's ISO 3166-2 code.

full_name_code_hash (for subcountry objects)

Given a sub country object, returns a hash of all full name/code pairs, keyed by sub country name.

code_full_name_hash (for subcountry objects)

Given a sub country object, returns a hash of all code/full name pairs, keyed by sub country code.

all_full_names (for subcountry objects)

Given a sub country object, returns an array of all sub country full names, sorted alphabetically.

all_codes (for subcountry objects)

Given a sub country object, returns an array of all sub country ISO 3166-2 codes, sorted alphabetically.

SEE ALSO

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

ISO 3166-2:1998 Codes for the representation of names of countries and their subdivisions - Part 2: Country subdivision code Also released as AS/NZS 2632.2:1999

Federal Information Processing Standards Publication 10-4 1995 April Specifications for COUNTRIES, DEPENDENCIES, AREAS OF SPECIAL SOVEREIGNTY, AND THEIR PRINCIPAL ADMINISTRATIVE DIVISIONS

<http://www.mindspring.com/~gwil/statoids.html>

Locale::Country
Lingua::EN::AddressParse
Geo::IP

LIMITATIONS

If a sub country's full name contains the word 'and', it is represented by an ampersand, as in 'Dumfries & Galloway'.

ISO 3166-2:1998 defines all sub country codes as being up to 3 letters and/or numbers. These codes are commonly accepted for countries like the USA and Canada. In Australia, Ireland and the UK, this method of abbreviation is not widely accepted. For example, the ISO code for 'New South Wales' is 'NS', but 'NSW' is the only abbreviation that is actually used. I could add a flag to enforce ISO-3166-2 codes if needed.

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.

The ISO 3166-2 standard will typically list more than one type of sub country for each country. For example, Australia has states and territories, Italy has provinces and regions. Normally I use all the different types of sub country. This module will not give you the type of each individual subcountry. It could be recorded if needed, but would take a lot of effort. Instead, the most common type of sub country is recorded for each country. So for Australia, this would be 'State'.

The following 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, such as a province and a geographical unit

AZERBAIJAN : Länkäran; LA (the City), LAN (the Rayon)
AZERBAIJAN : Säki; SA,SAK
AZERBAIJAN : Susa; SS,SUS
AZERBAIJAN : Yevlax; YE,YEV
INDONESIA  : Kalimantan Timur; KI,KT
LAOS       : Vientiane VI,VT
MOLDOVA    : Hahul; CA,CHL
MOLDOVA    : Bubasari; DU,DBI
MOLDOVA    : Hrhei; OR,OHI
MOLDOVA    : Coroca; SO,SOA
MOLDOVA    : Gngheni; UN,UGI
MOZAMBIQUE : Maputo; MPM,L

FIPS codes are not provided for all sub countries.

BUGS

None known

COPYRIGHT

Copyright (c) 2000-2003 Kim Ryan. All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of the Perl Artistic License

AUTHOR

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

CREDITS

Alastair McKinstry provided many of the sub country codes and names.

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

Mark Summerfield and Guy Fraser provided the list of UK counties.

TJ Mather supplied the FIPS codes and many ammendments to the sub country data

Code/Sub country data. Comments (lines starting with #) and blank lines are ignored. Read in at start up by first un-named block. Format is:

Country=<COUNTRY NAME> SubCountryType=<Sub Country Type> # optional field, specify state, county etc Code=<COUNTRY CODE> # from ISO 3166-1 format

ISO3166-2 Code:FIPS10-4 Code:Full Name ISO3166-2 Code:FIPS10-4 Code:Full Name ISO3166-2 Code:FIPS10-4 Code:Full Name

...

Country=<COUNTRY NAME> ...

cpanm Locale::SubCountry::World

perl -MCPAN -e shell
install Locale::SubCountry::World