Phone number formatter

What each column means

e164

The form to store, and to hand to an SMS or voice API: a plus sign, the calling code and the national number, with no spaces and no trunk prefix. The E.164 glossary entry says why a number needs its country to get there.

national · international

The number written for a reader inside its own country, with the trunk prefix where the country has one, and for a reader abroad, without it. An extension is kept in both and left out of e164, which cannot carry one.

country

The region whose plan the number belongs to, read from the number itself: +1 and +7 are each shared by several regions. Empty for the codes that belong to no country, such as +800.

plan line type

The type the metadata gives the range the number sits in, not the number's own history: a ported number keeps its range's type. The North American plan hands out mobile and landline numbers from the same blocks, so +1 numbers answer fixed_line_or_mobile; why, and what the block holder can settle.

time zone · local time

The zones libphonenumber names for the range, narrowed to the number's own country: where the range is, never where the person is. The local time is read when you press Format and shown only when every zone shares one UTC offset.

fits the plan

Yes when the metadata lists the number as valid, or when it sits in a range reserved for fiction that declares a line type, such as Ofcom's drama numbers. It is not the lookup's valid: the phone number lookup also reads the regulator's allocation table where one is installed, and answers valid false with the reason unassigned_block for a number in a block nobody holds, except a number in a range reserved for fiction, which stays valid.

reason and did you mean

A number that does not fit carries the reason the lookup gives (missing_country, too_short, invalid_number and the rest are in the reason reference) and, when exactly one other reading of its digits fits a plan, with a plus in front or with a foreign international prefix such as 011 removed, that reading as a suggestion. It is never applied, and a reading in a block the regulator lists as unassigned is not offered unless a range reserved for fiction claims it.

Trunk prefixes: dialled at home, dropped after the calling code

A trunk prefix is the digit or digits dialled in front of a number inside its own country and left out after the calling code. Of the 245 numbering regions in libphonenumber 9.0.40, 113 use 0, 101 have none and 31 use another prefix. In 17 of the regions without one, a number can itself start with a 0, which then stays in international and E.164 form.

That is why +44 (0)20 7946 0018 is wrong. ITU-T Recommendation E.123 uses parentheses for digits that are not always dialled and says they should not be used in an international number (clause 7.2), and it notes that callers abroad have to leave out a foreign trunk prefix (clause 2.8). This formatter, like libphonenumber, reads that spelling as +44 20 7946 0018; a system that keeps every digit stores +4402079460018, which is not a number in the UK plan.

The opposite mistake hits Italy, Vatican City, Benin, Gabon and San Marino. There is no trunk prefix there, and a landline number starts with a 0 that belongs to it: 02 1234 5678 is +39 02 1234 5678, E.164 +390212345678. A system that strips a leading 0 after every calling code drops a digit of the number itself.

Regions whose trunk prefix is not 0, or whose numbers keep a leading 0

The North American plan writes its numbers without the trunk 1, which is also its calling code; E.123 gives the zone its own national notation for that reason (clause 2.4). A ~ in a prefix means wait for a second dial tone (clause 7.6): 8~10 is 8, the tone, then 10. Which line types keep a 0 is read from the metadata's example numbers, so it says an example of that type starts with 0, not that every number does. Every example is libphonenumber's own, not a subscriber's number.

International call prefixes other than 00

The international prefix is what is dialled to leave a country, and what the + stands for in a written number. 185 of the 245 regions dial 00, or name it as the preferred choice among several. The rest dial:

"More than one" is where the metadata stores a pattern of several prefixes and names no preferred one. Source for both tables: libphonenumber 9.0.40 (Apache License 2.0), read on this server. Each region's calling code and an example number per line type are on its page under phone facts by country.

Frequently asked questions

Longer lists: batch and bulk jobs in the API, or SPAW_PHONE in Google Sheets.