plucky (3) Number::Phone::Country.3pm.gz

Provided by: libnumber-phone-perl_4.0005-1_all bug

NAME

       Number::Phone::Country - Lookup country of phone number

SYNOPSIS

         use Number::Phone::Country;

         #returns 'CA', '1' for Canada
         my ($iso_country_code, $idd) = Number::Phone::Country::phone2country_and_idd("1 (604) 111-1111");

       or

         use Number::Phone::Country qw(uk);

         my ($iso_country_code, $idd) = Number::Phone::Country::phone2country_and_idd(...);

       or

         #returns '49'
         my $idd = Number::Phone::Country::country_code("DE");

INCOMPATIBLE CHANGES

   from version 2.00 onwards
       As of version 2.00 the "phone2country" function is no longer exported. It has been deprecated since
       version 0.5, which was released in 2004. Use of the "noexport" flag will now result in warnings. The
       first release after August 2026 will upgrade those to be fatal errors. At the same time warnings about
       any other unknown params will also be upgraded to be fatal.

DESCRIPTION

       This module looks up up the country based on a telephone number.  It uses the International Direct
       Dialing (IDD) prefix, and lookups North American numbers using the Area Code, in accordance with the
       North America Numbering Plan (NANP).  It can also, given a country, tell you the country code, and the
       prefixes you need to dial when in that country to call outside your local area or to call another
       country.

       Be aware that the ISO code for the United Kingdom is GB, not UK.  If you would prefer UK, pass the "uk"
       flag as demonstrated in the "SYNOPSIS".

       I have put in number ranges for Kosovo, which does not yet have an ISO country code.  I have used XK, as
       that is the de facto standard as used by numerous international bodies such as the European Commission
       and the IMF.  I previously used KOS, as used by the UN Development Programme.  This may change again in
       the future.

FUNCTIONS

       The following functions are available:

       country_code($country)
           Returns the international dialing prefix for this country - eg, for the UK it returns 44, and for
           Canada it returns 1.

       idd_code($country)
           Returns one, of possibly multiple, International Direct Dialing prefixes for the given ISO Alpha-2
           country code.  Returns nothing if the country code is not recognised or not supported.

           The IDD prefix is needed to make a call from a country to another country.  For example, when calling
           the UK from the US, the caller must first dial the IDD prefix 011 to setup an international call,
           followed by the country calling code for the UK (44), followed by the UK national number.

           Many telephone systems allow the caller to dial a plus sign prefix (+) in place of the IDD, in which
           case the system replaces the plus sign with the correct IDD prefix for the caller's country.

           Some countries have more than one IDD code, allowing the caller to route their calls through specific
           networks.  "idd_code" only returns one code.  See "idd_regex" if you need to match a number against
           known IDD prefixes for a given country.

       idd_regex($country)
           Returns a regular expression that matches against known International Direct Dialing prefixes for the
           given ISO Alpha-2 country code.  Returns nothing if the country code is not recognised or not
           supported.

           As an example, the regular expression for Australia (AU) will match a number of IDD prefixes,
           including 0011, 0014, and 0015, making it possible to determine that 001516502530000 could be a US
           number being dialled from Australia.

           Be aware that some numbers will match against IDD prefixes from multiple countries.  Other numbers
           will be valid national numbers for one country, and valid international numbers when called for other
           countries.  For example, 01143662111 is a valid national number for Sheffield, England.  It could
           also be a valid number in Austria:

           Calling from within the UK:

            Area code:     0114
            Subscriber:    366 2111
            National:      0114 366 2111
            International: +441143662111

           Calling from a country that uses the NANP (North American Numbering Plan):

            IDD:           011
            Country code:  43 (Austria)
            Area code:     0662 (Salzburg)
            Subscriber:    111
            National:      0662 111
            International: +43662111

       ndd_code($country)
           Returns the National Direct Dialing prefix for the given country.  This is the prefix used to make a
           call within a country from one city to another.  This prefix may not be necessary when calling
           another city in the same vicinity.  This is followed by the city or area code for the place you are
           calling.  For example, in the US, the NDD prefix is "1", so you must dial 1 before the area code to
           place a long distance call within the country.

       phone2country($phone)
           DEPRECATED Returns the ISO country code (or XK for Kosovo) for a phone number.  eg, for +441234567890
           it returns 'GB' (or 'UK' if you've told it to).

       phone2country_and_idd($phone)
           Returns a list containing the ISO country code and IDD prefix for the given phone number.  eg for
           +441234567890 it returns ('GB', 44).

SEE ALSO

       Parse::PhoneNumber

BUGS

       It has not been possible to maintain complete backwards compatibility with the original 0.01 release.  To
       fix a bug, while still retaining the ability to look up plain un-adorned NANP numbers without the +1
       prefix, all non-NANP numbers *must* have their leading + sign.

       Another incompatibility - it was previously assumed that any number not assigned to some other country
       was in the US.  This was incorrect for (eg) 800 numbers.  These are now identified as being generic NANP
       numbers.

       Will go out of date every time the NANP has one of its code splits/overlays.  So that's about once a
       month then.  I'll do my best to keep it up to date.

WARNING

       The Yugoslavs keep changing their minds about what country they want to be and what their ISO 3166 code
       and IDD prefix should be.  YU? CS? RS? ME?  God knows.  And then there's Kosovo ...

AUTHOR

       now maintained by David Cantrell <david@cantrell.org.uk>

       originally by TJ Mather, <tjmather@maxmind.com>

       country/IDD/NDD contributions by Michael Schout, <mschout@gkg.net>

       Thanks to Shraga Bor-Sood for the updates in version 1.4.

       Copyright 2003 by MaxMind LLC

       Copyright 2004 - 2024 David Cantrell

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