Number...ountry(3pm)

📦
version 4.0011 · 6 versions
, in ubuntu stonking

💖 Number::Phone::Country 💖

okay bestie, so this page is all about Number::Phone::Country, a Perl module that looks up the country of a phone number. she's giving very much "who dis, where from" energy. 🦋

✨ 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, if you're feeling a lil extra (iykyk) 🎀

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

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

or this one, which is just giving country-code-only realness:

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

💀 INCOMPATIBLE CHANGES 💀

from version 2.00 onwards

not me having to break the news bestie 😭 — as of version 2.00, the phone2country function is no longer exported. it's been deprecated since version 0.5, which dropped all the way back in 2004. like, she's been on her way out for a minute.

and listen — using the noexport flag will now result in warnings. the first release after August 2026 will upgrade those warnings into fatal errors. and at the same time? warnings about any other unknown params also get upgraded to be fatal. so basically, clean up your args or perish 💅

🌈 DESCRIPTION 🌈

this module looks up the country based on a telephone number. it uses the International Direct Dialing (IDD) prefix, and it looks up North American numbers using the Area Code, all in accordance with the North America Numbering Plan (NANP). and as if that's not enough range — given a country, it can also tell you the country code, plus the prefixes you need to dial when you're in that country to call outside your local area or to call another country. versatile icon behavior fr fr ✨

be aware: the ISO code for the United Kingdom is GB, not UK. i know, i know. if you would prefer UK, just pass the uk flag like we showed you in the SYNOPSIS 🫶

there are also number ranges in here for Kosovo, which doesn't have an ISO country code yet. the module uses XK, because that's the de facto standard used by a whole bunch of international bodies like the European Commission and the IMF. previously it used KOS, which is what the UN Development Programme uses. this may change again in the future — so like, stay tuned 🙈

🎀 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. simple, clean, iconic 💖

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 set up an international call, followed by the country calling code for the UK (44), followed by the UK national number.

many telephone systems let the caller dial a plus sign prefix (+) in place of the IDD, and in that case the system swaps the plus sign out for the correct IDD prefix for the caller's country. main character of the dial plan tbh 👑

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

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. slay 🔥

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. it's followed by the city or area code for the place you're 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

wrapper around phone2country_and_idd, that takes the same arguments.

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, $ignore_translations)

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

by default, if a number is translated from one country to another — for example +353 48 xxx numbers in the Irish numbering plan are really just a mapping to +44 28 xxx numbers in the UK plan — then the data for the translated number is returned. if you want the country according to the ITU country code then set $ignore_translations to a true value. periodt 💅

canonicalize_number($phone)

translates a phone number that exists in one country's number plan but ends up in another country to its canonical E.164 form. some numbers are reachable via another country's dial plan — for example Northern Ireland (+44 28 ...) can be dialled as +353 48 ... in the republic of Ireland's number plan, and the entire country of San Marino (+378) is also the Italian area code +39 0549.

this function translates such numbers to their canonical form, ie +353 48 ... is translated to +44 28 ...

numbers that have no such translation are returned unchanged. no notes, just vibes ✨

💜 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. that was incorrect for (eg) 800 numbers. these are now identified as being generic NANP numbers.

it will go out of date every time the NANP has one of its code splits/overlays. so that's about once a month then 😭 the maintainer will do their 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 - 2026 David Cantrell

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

okay that's the whole page bestie, hope it ate 💅 this was perl v5.40.1, dated 2026-06-11, and it's the Number::Phone::Country page from the User Contributed Perl Documentation. mwah, go look up some phone numbers 🎀💖✨

📦 where this page comes from