In some cases, the library cannot tell if the leading digits of a phone number are intended to be the country calling code, or the start of the national significant number.

This affects primarily German phone numbers, where 49 is both a country calling code and an area code, and numbers of variable lengths are valid. The leading digits will only be interpreted as a country calling code if the number is not already considered a possible number for the region provided when parsing.

If you know that your numbers are always in the form <country calling code><national significant number>, it is safe to put a "+" in front to indicate this to the library.

To understand the behavior of functions, please refer to the documentation in the Javadoc/C++ header files. For example, see isPossibleNumberWithReason in PhoneNumberUtil.

Short numbers are out of scope of PhoneNumberUtil. For short numbers, use ShortNumberInfo.

Our phone number library can tell that a number range is valid when there is sufficient official documentation, with some latency after this fact is brought to our attention via issue reports or notifications (see below for more information on where our metadata comes from). A valid number range is one from which numbers can be freely assigned by carriers to users.

Do not rely on libphonenumber to determine whether numbers are currently assigned to a specific user and reachable. Some products (e.g. Google 2-step verification) do this with a verification step e.g. by sending an SMS or placing an automated phone call with a verification code). This is not technically feasible without such a verification step given the complicated international world we live in, with varying standardization practices in different regions.

Not necessarily. In some countries extra digits at the end are ignored. For example, dialling 1800 MICROSOFT in the US connects to +1 (800) MIC-ROSO. Moreover, during renumbering transitions, e.g. when all numbers are getting an extra 9 added to the front, some carriers will "fix" old numbers long after they're no longer working for the majority.

Rarely! Many people have phone numbers that do not belong to the country they live in. This applies particularly to mobile numbers, but may also be true for VoIP numbers etc. Note also that the regions your application supports may not be the same as the regions we support. For example, the Channel Islands such as "Jersey" have their own region code - JE. If you allow these users to sign up as a British user ("GB"), their phone numbers will not be considered valid for the region "JE".

One use-case where this method may be useful is if you want to see if a FIXED_LINE number for a business matches the country it is in, to try and spot data errors.

SMSs can be sent to TYPE_MOBILE or TYPE_FIXED_LINE_OR_MOBILE numbers. However, in some countries it is possible to configure other types, such as normal land-lines, to receive SMSs.

Some number ranges are explicitly defined as being for fixed-line or mobile phones. We even represent ranges defined as being "Mostly land-line" in this way.

The ability to keep your mobile phone number when changing carriers. To see whether a region supports mobile number portability use isMobileNumberPortableRegion.

Not all regions support mobile number portability. For those that don't, we return the carrier when available. For those that do, we return the original carrier for the supplied number.

libphonenumber does not support M2M numbers at the moment, but might in the future.

One of the reasons libphonenumber doesn't support M2M so far is because no one could explain their use to us sufficiently.

We don't require that a number to be supported by the library has a human at the other end since we already accept premium rate services and they might go to an automated system instead. But to date we only accept ranges that a human might call or send an SMS to.

M2M numbers would violate this assumption and we'd have to evaluate the consequences for existing APIs and clients if M2M numbers would be considered valid by the library. Clients of libphonenumber expect mobile and fixed-line numbers to have certain affordances, such as: Reachable for voice calls (and for mobile also SMS) as well as assuming standard cost. This expectation is broken by the lack of M2M standardization today.

Many people use this library for formatting the numbers of their contacts, for allowing people to sign up for services, for working out how to dial someone in a different country, for working out what kind of cost might be associated with a number in an advert, etc. We don't think the lack of M2M support hinders any of those use-case, but we might be wrong.

If you would like libphonenumber to support M2M numbers, please engage with the developer community at Support M2M numbers #680 with further information to address our questions and concerns such as:

• How to implement support? e.g. new category, new library or method to call - along with pros and cons, and impact on existing APIs
• Authoritative and specific documentation such as government sources since we currently have less than a dozen sources, which have varied definitions

More information and collabortation on this issue would be very welcomed!

Related issues: Support M2M numbers #680, #930: JTGlobal - an MNO based in the UK, #976: Norway, #985: South Africa, Vodacom, #910: Sweden, #657: Canada, #550: Belgium, #351: Norway, #332: Netherlands

We support parsing and storing numbers from a minimum length of two digits to a maximum length of 17 digits currently (excluding country calling code). The ITU standard says the national significant number should not be longer than fifteen digits, but empirically this has been proven not to be followed by all countries.

No, phone number formatting is country-specific and language-independent. E.g. formatting a US number in a French way (e.g. the way a France number is formatted) for a French user is undefined and wrong.

It is true that in some countries phone numbers are typically written using native, not ASCII, digits; our phone number library supports parsing these but doesn't support it at formatting time at the moment.

If we don't think we can guarantee that the number is diallable from the user's mobile phone, we won't return anything. This means that for numbers that we don't think are internationally diallable, if the user is outside the country we will return an empty string. Similarly, in Brazil a carrier code is essential for dialling long-distance domestically. If none has been provided at parsing time then we will return an empty string. If you get an empty string and are okay providing a number that may not be diallable, you can call another of our formatting numbers instead.

We use the word "metadata" to refer to all information about phone numbering in a particular country - what the country code, international and national dialling prefixes are, what carrier codes are operational, which phone numbers are possible or valid for a particular country, how to optimally format them, which prefixes represent a particular geographical area, etc.

In theory, phone numbering plans are all supposed to be administered through the ITU. Many countries' phone numbering plans may be found on the ITU website.

We receive automatic notifications when a new ITU plan has been filed, which may or may not be before it comes into effect.

Not every country files their numbering plans with the ITU nor are the plans filed with ITU always up to date. In some countries, the numbering plans are directly handled by a government authority, while in others, most of the work is done by telecom companies (the government's role being only to distribute ranges at the prefix level, with the actual partitioning within the prefix done by the telecom).

A large part of the data in PhoneNumberMetadata.xml comes from the ITU documents, but because they're sometimes insufficient, we also include data from other sources, including user bug reports, telecom company home pages and government telecommunication authorities.

There is no RFC indicating where the data comes from, or what format they're in.

We'd love to consume machine-readable numbering plan data (assigned ranges, carrier & geo mappings). If you can connect us with partners in the industry to achieve this, please do so. Thanks!

We only support a country if:

• The country has a single country calling code. For instance, Kosovo (XK) has been using three different country codes until 2017 - those of Serbia, Monaco and Slovenia. The relevant numbers will be marked as valid, but as belonging to Serbia, Monaco or Slovenia respectively. When Kosovo starts using its own country calling code of 383 it will be added to the metadata by itself. Similarly, Antarctica doesn't use its assigned country calling code of 672 - instead the bases belonging to different countries have different solutions. For example, Scott Base, belonging to New Zealand, has an area code that is part of the New Zealand phone number plan, and we support those numbers as valid numbers for NZ.
• The country still exists. For example, Yugoslavia (YU), Serbia and Montenegro (CS) and Netherlands Antilles (AN) have been dissolved and no longer exist as political entities so we do not support them.
• The country has some phone numbers in use that can be ascribed to it. For instance, Pitcairn Island has only around thirty inhabitants and they use satellite phones, so there is no numbering plan for Pitcairn Island. Similarly, Bouvet Island is an uninhabited Antarctic volcanic island with no telephone country code and no telephone connection, so we will not support it.
• It has an assigned region code. For instance, previously Kosovo did not have a region code assigned to it, so we could not support it until it was assigned XK by CLDR.

We support non-geographical entities that have been assigned country calling codes by the ITU where a numbering plan is available, e.g. "800" (International Freephone Service) and 870 (Inmarsat SNAC). However we do not support country calling codes that are only "reserved", or that no data is available for (namely 388 - listed as "Group of countries, shared code" and 991 - listed as "Trial of a proposed new international telecommunication public correspondence service, shared code".)

Although some numbers beginning with "001 803" or "007 803" do work in Indonesia to reach toll-free endpoints, these numbers are hard to support because they overlap with the international dialling prefix for Indonesia (IDD). It seems that since 803 is unassigned and not a valid country code, some local tel-companies in Indonesia hijack 803 and redirect it to their own services.

We have also found evidence that reaching some "00x 803" numbers cost local or national tariff, rather than the call being toll-free.

These numbers are not diallable from any other country using their IDD, and it's unclear whether all carriers in Indonesia support them. If we ever supported them, they would have to be added to the noInternationalDialling section, and it is likely some changes in the parsing code would have to be made to interpret the "00x" as something other than an IDD: this could have undesirable side-effects when parsing other numbers.

For JavaScript, Java and C++ there is the option to use a stripped-down version of the metadata. Currently this only removes the example number metadata, so the savings are not a lot, but we may revisit this.

Impact:

• getExampleNumber, getInvalidExampleNumber, getExampleNumberForType, getExampleNumberForNonGeoEntity will return null
• Binary size (or download size for JS) will be slightly smaller

JS: Simply include metadatalite.js instead of metadata.js in your project.

C++: Set the compiler flag USE_METADATA_LITE to ON using ccmake or similar.

Java: The metadata binary files can be generated using the ant build rules build-phone-metadata and build-short-metadata with lite-build set to true. This can be set in the build file itself.

When possible, use the latest version of libphonenumber.

For the other Maven artifacts, to find the version corresponding to a given version of libphonenumber, follow these steps:

• Go to the versioned GitHub tag, e.g. https://github.com/googlei18n/libphonenumber/find/v8.3.3
• Type pom.xml. This will surface all the pom.xml files as they were released at the chosen tag.
• Find the version you care about in the corresponding pom.xml file. Look for <version> in the top-level project element. For example, to find the version of the carrier jar corresponding to libphonenumber 8.3.3, open java/carrier/pom.xml at v8.3.3's search results. This is 1.56.
• If you depend on the carrier or geocoder jar, you also need to depend on the prefixmapper jar.

tl;dr: Do not call PhoneNumberUtil API on the main thread.

If you get surprising exceptions involving metadata loading, e.g. "missing metadata" exceptions when the metadata exists, then it's probably because you're loading resources on the main thread.

Please ensure that you don't call PhoneNumberUtil API on the main thread. Not loading resources in the main thread is the suggested best practice at the Android developer guide, and will prevent the issue reported in #265, #528, and #819.

You can manage your own resources by supplying your own MetadataLoader implementation to the PhoneNumberUtil instance. It is thus possible for your app to load the resources as Android assets, while libphonenumber loads Java resources by default. The result is that the files are read as native Android assets and so optimized for speed.

Here's the sample code for how to do it:

PhoneNumberUtil util = PhoneNumberUtil.createInstance(new MetadataLoader() {
  @Override
  public InputStream loadMetadata(String metadataFileName) {
    return Application.getContext().getAssets().open("some/asset/path" + metadataFileName);
  }
});

You also need to copy the binary metadata files into your app's asset directory, and automate updating them from upstream. To avoid net increase of app size, remove them from libphonenumber.

The libphonenumber team's support of the C++ library on Windows is primarily to support Chromium's build environment, and we depend on the community to support other Windows build environments / build chains. We list here some known issues that would benefit from open-source collaboration. If you can contribute a PR or review and test out someone else's PR, please chime in on these links, or email the discussion group:

• #1000 to provide a Windows DLL.
• #1010 to require Visual Studio 2015 update 2 or later on Windows
• PR #1090 / #824 to "Replace POSIX directory operations by Boost Filesystem"
• #1307 to use readdir instead of readdir_r
• #1555 to allow Windows to build cpp library with pthreads for multi-threading