Perl 5 version 26.2 documentation



Locale::Country - standard codes for country identification


  1. use Locale::Country;
  2. $country = code2country('jp' [,CODESET]); # $country gets 'Japan'
  3. $code = country2code('Norway' [,CODESET]); # $code gets 'no'
  4. @codes = all_country_codes( [CODESET]);
  5. @names = all_country_names();
  6. # semi-private routines
  7. Locale::Country::rename_country('gb' => 'Great Britain');


This module provides access to several code sets that can be used for identifying countries, such as those defined in ISO 3166-1.

Most of the routines take an optional additional argument which specifies the code set to use. If not specified, the default ISO 3166-1 two-letter codes will be used.


There are several different code sets you can use for identifying countries. A code set may be specified using either a name, or a constant that is automatically exported by this module.

For example, the two are equivalent:

  1. $country = code2country('jp','alpha-2');
  2. $country = code2country('jp',LOCALE_CODE_ALPHA_2);

The codesets currently supported are:

  • alpha-2, LOCALE_CODE_ALPHA_2

    This is the set of two-letter (lowercase) codes from ISO 3166-1, such as 'tv' for Tuvalu.

    This is the default code set.

  • alpha-3, LOCALE_CODE_ALPHA_3

    This is the set of three-letter (lowercase) codes from ISO 3166-1, such as 'brb' for Barbados. These codes are actually defined and maintained by the U.N. Statistics division.


    This is the set of three-digit numeric codes from ISO 3166-1, such as 064 for Bhutan. These codes are actually defined and maintained by the U.N. Statistics division.

    If a 2-digit code is entered, it is converted to 3 digits by prepending a 0.


    The IANA is responsible for delegating management of the top level country domains. The country domains are the two-letter (lowercase) codes from ISO 3166 with a few other additions.

  • un-alpha-3, LOCALE_CODE_UN_ALPHA_3
  • un-numeric, LOCALE_CODE_UN_NUMERIC

    The UN maintains a list of codes that is similar, but not identical, to the standard ISO 3166 lists. They maintain a 3-letter code (similar to alpha-3) and a numeric code (similar to numeric).

  • genc-alpha-2, LOCALE_CODE_GENC_ALPHA_2
  • genc-alpha-3, LOCALE_CODE_GENC_ALPHA_3
  • genc-numeric, LOCALE_CODE_GENC_NUMERIC

    The GENC codes are the US Government codes that replace the FIPS-11 codes. They are based on, but not identical to the standard ISO 3166 lists.

NOTE: As of version 3.27, the FIPS code set is no longer supported. See the Locale::Codes::Changes document for details.


  • code2country(CODE [,CODESET] [,'retired'])
  • country2code(NAME [,CODESET] [,'retired'])
  • country_code2code(CODE ,CODESET ,CODESET2)
  • all_country_codes([CODESET] [,'retired'])
  • all_country_names([CODESET] [,'retired'])
  • Locale::Country::rename_country(CODE ,NEW_NAME [,CODESET])
  • Locale::Country::add_country(CODE ,NAME [,CODESET])
  • Locale::Country::delete_country(CODE [,CODESET])
  • Locale::Country::add_country_alias(NAME ,NEW_NAME)
  • Locale::Country::delete_country_alias(NAME)
  • Locale::Country::rename_country_code(CODE ,NEW_CODE [,CODESET])
  • Locale::Country::add_country_code_alias(CODE ,NEW_CODE [,CODESET])
  • Locale::Country::delete_country_code_alias(CODE [,CODESET])

    These routines are all documented in the Locale::Codes::API man page.



See Locale::Codes for full author history.

Currently maintained by Sullivan Beck (


  1. Copyright (c) 1997-2001 Canon Research Centre Europe (CRE).
  2. Copyright (c) 2001-2010 Neil Bowers
  3. Copyright (c) 2010-2016 Sullivan Beck

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