libphonenumber Documentation

Google's common Java, C++ and JavaScript library for parsing, formatting, and validating international phone numbers.

18,321 stars C++ C++ 7 files · ~9,948 tokens
RAW Doc

Technical Documentation: google/libphonenumber

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`)

What is it?

Google's common Java, C++ and JavaScript library for parsing, formatting, and
validating international phone numbers. The Java version is optimized for
running on smartphones, and is used by the Android framework since 4.0 (Ice
Cream Sandwich).

Highlights of functionality

  • Parsing, formatting, and validating phone numbers for all countries/regions
    of the world.
  • getNumberType - gets the type of the number based on the number itself;
    able to distinguish Fixed-line, Mobile, Toll-free, Premium Rate, Shared
    Cost, VoIP, Personal Numbers, UAN, Pager, and Voicemail (whenever feasible).
  • isNumberMatch - gets a confidence level on whether two numbers could be
    the same.
  • getExampleNumber and getExampleNumberForType - provide valid example
    numbers for all countries/regions, with the option of specifying which type
    of example phone number is needed.
  • isPossibleNumber - quickly guesses whether a number is a possible
    phone number by using only the length information, much faster than a full
    validation.
  • isValidNumber - full validation of a phone number for a region using
    length and prefix information.
  • AsYouTypeFormatter - formats phone numbers on-the-fly when users enter
    each digit.
  • findNumbers - finds numbers in text.
  • PhoneNumberOfflineGeocoder - provides geographical information related to
    a phone number.
  • PhoneNumberToCarrierMapper - provides carrier information related to a
    phone number.
  • PhoneNumberToTimeZonesMapper - provides timezone information related to a
    phone number.

Demo

Java

The Java demo is updated with a slight
delay after the GitHub release.

Last demo update: v9.0.41.

Note: Even though the library (main branch/maven release)
is at v8.12.57, because of some deployment issues, we were unable to update the
Java demo with the new binary version. We will soon fix this. Meantime, please
use JS demo.

If this number is lower than the latest release's version
number, we are between
releases and the demo may be at either version.

Demo App

There is a demo Android App called E.164 Formatter in this
repository. The purpose of this App is to show an example of how the library can
be used in a real-life situation, in this case specifically in an Android App
using Java.

JavaScript

The JavaScript
demo
may be run at various tags; this link will take you to master.

Java code

To include the Java code in your application, either integrate with Maven (see
wiki) or download the latest
jars from the Maven
repository.

Javadoc

Javadoc is automatically updated to reflect the latest release at
https://javadoc.io/doc/com.googlecode.libphonenumber/libphonenumber/.

Versioning and Announcements

We generally choose the release number following these guidelines.

If any of the changes pushed to master since the last release are incompatible
with the intent / specification of an existing libphonenumber API or may cause
libphonenumber (Java, C++, or JS) clients to have to change their code to keep
building, we publish a major release. For example, if the last release were
7.7.3, the new one would be 8.0.0.

If any of those changes enable clients to update their code to take advantage
of new functionality, and if clients would have to roll-back these changes in
the event that the release was marked as "bad", we publish a minor release. For
example, we'd go from 7.7.3 to 7.8.0.

Otherwise, including when a release contains only
metadata changes, we publish a sub-minor release,
e.g. 7.7.3 to 7.7.4.

Sometimes we make internal changes to the code or metadata that, while not
affecting compatibility for clients, could affect compatibility for porters
of the library. For such changes we make announcements to
libphonenumber-discuss. Such changes
are not reflected in the version number, and we would publish a sub-minor
release if there were no other changes.

Want to get notified of new releases? During most of the year, excepting
holidays and extenuating circumstances, we release fortnightly. We update
release tags and
document detailed release notes.
We also send an announcement to libphonenumber-discuss for every
release.

Quick Examples

Let's say you have a string representing a phone number from Switzerland. This
is how you parse/normalize it into a PhoneNumber object:

java
String swissNumberStr = "044 668 18 00";
PhoneNumberUtil phoneUtil = PhoneNumberUtil.getInstance();
try {
  PhoneNumber swissNumberProto = phoneUtil.parse(swissNumberStr, "CH");
} catch (NumberParseException e) {
  System.err.println("NumberParseException was thrown: " + e.toString());
}

At this point, swissNumberProto contains:

json
{
  "country_code": 41,
  "national_number": 446681800
}

PhoneNumber is a class that was originally auto-generated from
phonenumber.proto with necessary modifications for efficiency. For details on
the meaning of each field, refer to resources/phonenumber.proto.

Now let us validate whether the number is valid:

java
boolean isValid = phoneUtil.isValidNumber(swissNumberProto); // returns true

There are a few formats supported by the formatting method, as illustrated
below:

java
// Produces "+41 44 668 18 00"
System.out.println(phoneUtil.format(swissNumberProto, PhoneNumberFormat.INTERNATIONAL));
// Produces "044 668 18 00"
System.out.println(phoneUtil.format(swissNumberProto, PhoneNumberFormat.NATIONAL));
// Produces "+41446681800"
System.out.println(phoneUtil.format(swissNumberProto, PhoneNumberFormat.E164));

You could also choose to format the number in the way it is dialed from another
country:

java
// Produces "011 41 44 668 1800", the number when it is dialed in the United States.
System.out.println(phoneUtil.formatOutOfCountryCallingNumber(swissNumberProto, "US"));

Formatting Phone Numbers 'as you type'

java
PhoneNumberUtil phoneUtil = PhoneNumberUtil.getInstance();
AsYouTypeFormatter formatter = phoneUtil.getAsYouTypeFormatter("US");
System.out.println(formatter.inputDigit('6'));  // Outputs "6"
...  // Input more digits
System.out.println(formatter.inputDigit('3'));  // Now outputs "650 253"

Geocoding Phone Numbers

java
PhoneNumberOfflineGeocoder geocoder = PhoneNumberOfflineGeocoder.getInstance();
// Outputs "Zurich"
System.out.println(geocoder.getDescriptionForNumber(swissNumberProto, Locale.ENGLISH));
// Outputs "Zürich"
System.out.println(geocoder.getDescriptionForNumber(swissNumberProto, Locale.GERMAN));
// Outputs "Zurigo"
System.out.println(geocoder.getDescriptionForNumber(swissNumberProto, Locale.ITALIAN));

Mapping Phone Numbers to original carriers

Caveat: We do not provide data about the current carrier of a phone number, only
the original carrier who is assigned the corresponding range. Read about number
portability.

java
PhoneNumber swissMobileNumber =
    new PhoneNumber().setCountryCode(41).setNationalNumber(798765432L);
PhoneNumberToCarrierMapper carrierMapper = PhoneNumberToCarrierMapper.getInstance();
// Outputs "Swisscom"
System.out.println(carrierMapper.getNameForNumber(swissMobileNumber, Locale.ENGLISH));

More examples on how to use the library can be found in the unit
tests.

Third-party Ports

Several third-party ports of the phone number library are known to us. We share
them here in case they're useful for developers.

However, we emphasize that these ports are by developers outside the
libphonenumber project. We do not evaluate their quality or influence their
maintenance processes.

Alternatives to our own versions:

  • Android-optimized: Our Java version loads the metadata from
    Class#getResourcesAsStream and asks that Android apps follow the Android
    loading best practices of repackaging the metadata and loading from
    AssetManager#open() themselves
    (FAQ).
    If you don't want to do this, check out the port at
    https://github.com/MichaelRocks/libphonenumber-android, which does repackage
    the metadata and use AssetManager#open(), and may be depended on without
    needing those specific loading optimizations from clients. You should also check
    out the port at https://github.com/lionscribe/libphonenumber-android which also
    supports geocoding, and only requires a one line code change.
  • Javascript: If you don't want to use our version, which depends on Closure,
    there are several other options, including
    https://github.com/catamphetamine/libphonenumber-js - a stripped-down
    rewrite, about 110 KB in size - and
    https://github.com/seegno/google-libphonenumber - a browserify-compatible
    wrapper around the original unmodified library installable via npm, which
    packs the Google Closure library, about 420 KB in size.

Tools based on libphonenumber metadata:

Overview (`javascript/README.md`)

Info:

Google's JavaScript library for parsing, formatting, and validating
international phone numbers.

How to setup:

  1. Checkout closure-library, closure-compiler, closure-linter and python-gflags next to libphonenumber:

  • git clone https://github.com/google/libphonenumber/

  • git clone https://github.com/google/closure-library/

  • git clone https://github.com/google/closure-compiler.git

  • git clone https://github.com/google/closure-linter.git

  • git clone https://github.com/google/python-gflags.git

  1. We officially support only these versions of these dependencies:

  • Closure library: v20201006

  • Closure compiler: v20210302

  • Closure linter: v2.3.19

  • Python gflags: 3.1.2

Note: We were to build at latest versions of these dependencies, however, we cannot promise that
we continue to support newer version of these dependencies. We learned that newer Closure binaries
deprecate older apis earlier, leading to build breakages.

If you don't checkout the dependencies next to libphonenumber:

  1. Change the path of the <script src=""> in the html pages to point to wherever base.js is located

  2. Update javascript/build.xml with the correct paths

  3. Run the unit tests to make sure everything is working. Open the following pages with your web browser:
    javascript/i18n/phonenumbers/phonenumberutil_test.html
    javascript/i18n/phonenumbers/asyoutypeformatter_test.html

  4. Run the demo: javascript/i18n/phonenumbers/demo.html

How to compile:

  1. Build the Closure Compiler JAR file by following the directions on the
    Closure Compiler README.
    If this step doesn't work, try updating your local copy of each of the
    repositories listed above before filing an issue.

  2. Compile the demo.js and all its dependencies to one file: demo-compiled.js:
    ant -f javascript/build.xml compile-demo

  3. Run the compiled demo: javascript/i18n/phonenumbers/demo-compiled.html

How to use:

To use and compile the library in your own project, use the javascript/i18n/phonenumbers/demo.js as an example. You will need to goog.exportSymbol all the methods you use in your html so that the compiler won't rename them. You can then invoke the compiler similarly to how the compile-demo ant target in javascript/build.xml invokes it.

How to update:

The JavaScript library is ported from the Java implementation.
When the Java project gets updated follow these steps to update the JavaScript
project:

  1. If the protocol buffers (phonemetadata.proto and phonenumber.proto) have changed:
  • Manually update the .pb.js files with the changes of the .proto files.
  • Manually update the toJsArray() Java methods in tools/java/java-build/src/com/google/i18n/phonenumbers/BuildMetadataJsonFromXml.java
  • Build tools/java/java-build/target/java-build-1.0-SNAPSHOT-jar-with-dependencies.jar by running: mvn -f tools/java/java-build/pom.xml package
  1. If the phone number metadata in the XML format has changed resources/PhoneNumberMetadata.xml run the following commands to regenerate metadata.js and metadatafortesting.js:

ant -f java/build.xml build-js-metadata

  1. Manually port any changes of the Java code to the JavaScript code:
  • PhoneNumberUtil.java => phonenumberutil.js
  • AsYouTypeFormatter.java => asyoutypeformatter.js
  • PhoneNumberUtilTest.java => phonenumberutil_test.js
  • AsYouTypeFormatterTest.java => asyoutypeformatter_test.js
  1. Run the Closure Compiler to get your changes syntax and type checked. This will also generate demo-compiled.js used by demo-compiler.html

ant -f javascript/build.xml compile

  1. Run the Closure Linter to lint the JavaScript files:

ant -f javascript/build.xml lint

Missing functionality:

  1. JS port does not support extracting phone-numbers from text (findNumbers).
  2. JS port does not have an offline phone number geocoder.
  3. JS port of PhoneNumberUtil does not handle all digits, only a subset (JavaScript has no equivalent to the Java Character.digit).

Overview (`metadata/README.md`)

Libphonenumber Metadata Tools

This directory contains auxiliary libraries to support reading and manipulating
the CSV packaged metadata for libphonenumber client library. The initial release
of these libraries is purely concerned with processing the CSV files, and does
not yet contain the classes needed to convert the CSV data in the XML and other
text files used by libphonenumber.

Eventually it is expected that all the tooling for manipulating CSV metadata and
generating the XML files will be released here, at which time the CSV files will
become the source of truth for libphonenumber and the XML-based metadata and
other mapping files will be automatically derived from it.

About metadata.zip

It contains canonical metadata for the libphonenumber project, intended for use
by libphonenumber tools. CSV schemas are not promised to be stable.

Support and Api Stability

These libraries are not currently supported and do not provide a stable API;
use at your own risk.

There are no guarantees of stability for the APIs in this library, and while
they are not expected to change dramatically, API tweaks and bug fixes are
inevitable.

Issues and Contributions

Patches and pull requests cannot be accepted directly on this codebase, so if
you find an issue with these libraries, please open a new issue for it. However
we do not accept feature requests, or provide answers or technical support for
anything in this directory at this time.

Overview (`migrator/README.md`)

Migrator Library

The library takes in E.164 phone numbers with their corresponding BCP-47 country code. If inputted numbers match any of the supported internal renumbering ‘recipes’, which are created from official country documentation, said numbers will undergo a process of migration to convert them into the most up to date, dialable format. A given “recipe” is an internal record which holds data needed to migrate a stale number into one that is valid and dialable.

Capabilities

The migrator library can be used as either a command line tool or a web application. Both applications have the following capabilities:

Single Number Migration - input a single E.164 phone number with its corresponding BCP-47 country code. If there is an available migration recipe, the number will be converted to the new format based on the given recipe. The resulting string of the migration will be outputted to the console.

File Migration - input a text file location with one E.164 number per line along with the BCP-47 country code that corresponds to the numbers in the text file. All numbers in the text file that match available recipes will be migrated and a copy of the text file will be created with the updated numbers. The file path to the newly created text file will be outputted to the console.

Custom Recipe Migration - specify a custom recipe file to use for a migration instead of the internal maintained file. Custom recipe migrations will not check if converted numbers are valid based on country formats.

Migration Report - find all phone numbers in a given input that were migrated with given migration recipes. The report will also show the phone numbers that were already seen as valid before migrations as well as identify any numbers that were migrated into invalid formats based on known valid phone number ranges for the specified country code.

Command Line Usage

Required Parameters

(-n, --number | -f, --file) - either the phone number input or file input for a given migration. The number argument must be a single E.164 phone number. This number can be in strict E.164 format (“+841200000000”) or contain hyphens, spaces and curved brackets (“84 (120) 5555-555”). The file argument must be a path to a text file containing one E.164 phone number per line. For file migrations, the original text file will not be overwritten or stored and instead a new text file will be created containing the migrated version of each phone number or the original phone number when a migration did not take place. Original phone numbers will also be written to file when a given migration on a number is seen as invalid, producing a number not dialable for the given country, unless the --exportInvalidMigrations (see Optional Parameters) flag is specified. Note: all phone numbers entered for migration will be sanitized by removing any whitespace, hyphens or curved brackets. If the number after this process is still not in E.164 format, a migration will not be able to be performed on it.

-c, --countryCode - the BCP-47 country code that corresponds to the given phone number input. Only recipes from this country will be queried to find matching recipes for inputted numbers. (E.g. 44 for United Kingdom, 1 for US, 84 for Vietnam)

Optional Parameters

-r, --customRecipe - the path to a csv file containing custom migration recipes which follow the standard recipes file format. When using custom recipes, validity checks on migrated numbers will not be performed.

-e, --exportInvalidMigrations - the boolean command line flag specifying that text files created after the migration process for standard file migration job should contain the migrated version of a phone number when a migration has taken place on it, regardless of whether the migration resulted in an invalid phone number. By default, when a migrated number is seen as invalid, its original inputted representation is written to file. Note: this flag has no effect on a --number migration or a migration using a --customRecipe.

-h, --help - usage help

Installation and Setup

Start off by using git to download the latest version of the libphonenumber repository:

bash
git clone https://github.com/google/libphonenumber.git
cd libphonenumber
ls

The project must then be built with its dependencies using maven so that an executable jar can be created and run:

bash
# clean install metadata dependency to run migrator tool
cd metadata
mvn clean install

cd ../migrator
# clean install migrator to run migrator-servlet locally (optional)
mvn clean install

mvn clean compile assembly:single
cd target
ls

Single Number Migration

To perform a single number migration, the “countryCode” and “number” arguments must be specified. The tool will clean the number string to remove spaces, hyphens and curved brackets. Note that when a number contains spaces, the whole string must be enclosed with quotation marks.

An example of a valid migration of a Vietnam phone number is as shown below:

bash
java -jar migrator-1.0.0-jar-with-dependencies.jar --countryCode=84 --number=+841201234567

# Output:
# Migration of country code +84 phone number(s):
# Successful migration into: +84701234567

If the given number is already in a valid format for the given country code, a migration will not occur and instead a message explaining this will be printed:

bash
java -jar migrator-1.0.0-jar-with-dependencies.jar --countryCode=84 --number=+84(70)123-4567

# Output:
# Migration of country code +84 phone number(s):
# This number was seen to already be valid and dialable based on our data for the given country

The migrator tool will not migrate or validate a number that belongs to a different country from the specified country code. In such situations the tool will take no action:

bash
java -jar migrator-1.0.0-jar-with-dependencies.jar --countryCode=84 --number=”+44 77 12345 678”

# Output:
# Migration of country code +84 phone number(s):
# This number could not be migrated using any of the recipes from the given recipes file

File Migration

To perform a file migration, the “countryCode” and “file” arguments must be specified. The tool will generate a new text file with the outputted numbers once the migration is completed. For the following examples, “VietnamNumbers.txt” is a text file containing the phone numbers:

bash
VietnamNumbers.txt

84-1201234567
+84(121)7654321
+841225555555
84 120 1424534
+84709000000
+123829734972
373203934781

Migration using the country code +84:

bash
java -jar migrator-1.0.0-jar-with-dependencies.jar --countryCode=84 --file=../VietnamNumbers.txt

# Output: 
# Migration of country code +84 phone number(s):
# New numbers file created at: ./+84_Migration_VietnamNumbers.txt
bash
+84_Migration_VietnamNumbers.txt

+84701234567
+84797654321
+84775555555
+84701424534
+84709000000
+123829734972
373203934781

Migration using the country code +1:

bash
java -jar migrator-1.0.0-jar-with-dependencies.jar --countryCode=1 --file=../VietnamNumbers.txt 

# Output:
# Migration of country code +1 phone number(s):
# New numbers file created at: ./+1_Migration_VietnamNumbers.txt
bash
+1_Migration_VietnamNumbers.txt

84-1201234567
+84(121)7654321
+841225555555
84 120 1424534
+84709000000
+123829734972
373203934781

The above migration run created a text file with the same phone numbers as the original file because there are no +1 phone numbers in the file that could have been migrated.

Exporting Invalid Migrations

When performing standard migrations (migrations that do not use custom recipe files), there is a possibility that a migrated phone number is seen as being invalid for the given country code based on internal checks. This will occur when either an internal recipe is erroneous or the internal phone number ranges for a given country code do not properly reflect all valid numbers. In such cases, migrations will be rolled back and the original number will be written to file when running a “file” migration. To allow for invalid migrations to still be written to file, the “exportInvalidMigrations” flag must be specified.

The recipes table below shows a recipe with an error which will cause +84120 phone numbers to be converted invalidly to +8460 instead of +8470 which is the actual valid representation for the given Vietnamese numbers:

bash
Erroneous Internal Recipe File

Old Prefix   ;   Old Length  ;  Country Code   ;    Old Format     ;    New Format     ;  Description
84120        ;   12          ;  84             ;    xx120xxxxxxx   ;    xx60xxxxxxx    ;  Redial 84120 with 8470
84121        ;   12          ;  84             ;    xx121xxxxxx    ;    xx79xxxxxxx    ;  Redial 84121 with 8479

Below is the file input for the example migration runs:

bash
VietnamNums.txt

84-1201234567
+84(121)7654321

Example 1 - export original numbers (default):

bash
java -jar migrator-1.0.0-jar-with-dependencies.jar --countryCode=84 --file=../VietnamNums.txt 

# Output:
# Migration of country code +84 phone number(s):
# New numbers file created at: ./+84_Migration_VietnamNums.txt

The created text file will use the original number for the +84120 migration due to the migration being invalid.

bash
+84_Migration_VietnamNums.txt

84-1201234567
+84797654321

Example 2 - export invalid migrations:

bash
java -jar migrator-1.0.0-jar-with-dependencies.jar --countryCode=84 --file=../VietnamNums.txt --exportInvalidMigrations

# Output:
# Migration of country code +84 phone number(s):
# New numbers file created at: ./+84_Migration_VietnamNums.txt

Even though the migration was invalid, the newly created text file will use the migrated number for the +84120 migration because the file is set to be exported with invalid migrations.

bash
+84_Migration_VietnamNums.txt

+84601234567
+84797654321

Custom Recipe Migrations

Custom recipe migrations can be performed on both “number” and “file” type migrations. The additional requirement is that there is a “customRecipe” argument which points to a csv file containing a recipes table in the standard table format. The following is an example of a valid custom recipe file to be used.

bash
CustomRecipes.csv

Old Prefix ; Old Length ; Country Code ;  Old Format    ;  New Format   ; Description
123        ; 7          ; 1            ;  xx3xxxx       ;  xx99xxxx     ; Custom recipe, replace 3 with 99
001234     ; 7          ; 00           ;  xxxxxxx       ;  xx5xxxxx     ; Custom recipe, add 5 to third index

The above recipes file can be used in place of internal recipes by specifying in the following way:

bash
java -jar migrator-1.0.0-jar-with-dependencies.jar --countryCode=00 --number=0012345 --customRecipe=./CustomRecipes.csv

# Output:
# Migration of country code +00 phone number(s):
# Successful migration into: +00512345

Creating Custom Recipes.csv Files

A Recipes.csv file holds a table containing migration information for all known recipes. A given “recipe” is a row within the table which holds data needed to migrate a stale number into one that is valid and dialable.

When creating custom recipe files to use, there should never be a case where two recipes can be used to renumber one stale number so as a result, a given stale number can only ever match with one row in a Recipes table. Each column in the file must be separated using ; and the table must have the following columns:

Prefix (key) - the prefix of the possible stale numbers that can be represented by the row. For example, the prefix of the number “12345” could be “12”. Please note that the prefix cannot be the actual number so for the example case, the prefix could not be “12345”.

Length (key) - the length of all numbers that can be represented in the row. For example a length of 5 for a prefix of “1234” could represent numbers: “12340”, “12341”, “12342”, “12343”, ...

Old Format - represents what digits in the old format need to change where every digit that needs to stay the same is represented as an ‘x’
E.g. the number 7 at the 3rd index of a 4 digit number needs to be removed/replaced. This number is always 7 → xx7x
E.g. an addition needs to happen for a 4 digit number and no digits from the original format need to be changed, so none of the original digits need to be altered → xxxx

New Format - represents what the new number format should be. ‘x’ values represent digits from the original number that will stay the same.
E.g. digits ‘98’ need to be added at the start of an originally 4 digit number → 98xxxx
E.g. no digits need to be added because a removal took place. A 5 digit number has now become a 4 digit number → xxxx

Description - text specifying what the change is in words. This column is used purely for debugging purposes and will help easily diagnose issues with recipes quickly when the strings in the ‘Old Format’ or ‘New Format’ columns are incorrect.

Web Application

Please click here to view the web application version of the migrator tool.

About validation of phone numbers:

APIs and data in libphonenumber/metadata/ are used for validating phone numbers. More details in metadata/README.

Privacy

Both web application and command line versions of the migrator tool require an input of either a single string E.164 phone number or a text file containing one E.164 phone number per line. After the tool has completed the migration process, this data, along with any resulting data, is never written to any records or stored for later use.

Disclaimer

The migration library is designed to only migrate E.164 phone numbers using internally maintained migration “recipes”. The library will not attempt to migrate national phone numbers or format non-E.164 phone numbers prior to migrations in order for said numbers to be in E.164 format. Only recipes from the specified country code will be used to perform migrations on a given number(s) input. This means that even if a stale E.164 phone number from country A has a recipe that can be used to migrate it successfully but --countryCode=B is inputted as the command line argument, the phone number will not be migrated.

For standard migrations using internal recipes, it is possible for E.164 phone numbers to be migrated to a format which the library deems as being invalid. The validity of phone numbers is checked using metadata containing valid number ranges for all countries. As a result, a phone number migration will be seen as invalid if either the metadata of valid number ranges does not reflect the given format correctly or if there is an error with the used recipe internally. In either case, please file a new issue following the guidance of how to create one here in order to resolve the issue. For --file number inputs, invalid migrations by default will not be written to the created text file containing the updated phone numbers and instead, the original number which correlates to the migration will be used. If you would like to include invalid migration results in the newly created text file, specify this by using the --exportInvalidMigrations command line flag.

When using the --customRecipe argument, all numbers that match a given recipe from the number input will be migrated. These migrations will not be checked for validity based on internal metadata of valid phone number ranges. This means that for custom recipe migrations, there is no perception of invalid migrations.

License

See LICENSE file for Terms and Conditions.

Overview (`java/demo/README.md`)

Running the demo

1. Install Google Cloud SDK

Linux

Install the Appengine SDK.

$ sudo apt-get install google-cloud-sdk-app-engine-java

Mac

Install the Google Cloud SDK.

$ brew install google-cloud-sdk

Use GCloud CLI to install the Java Appengine

$ gcloud components install app-engine-java

2. Add IDE Plugin

Intellij

Install Cloud Code Plugin for Intellij

If you have worked with the App Engine Plugin before,
please migrate.

Eclipse

Install Cloud Code Plugin for Eclipse

Visual Studio Code

Install Cloud Code Plugin for Visual Studio Code

3. Run

Most IDEs should autodetect your configuration after installing the plugin (and
restart)

(Optional) Run Natively

This is not recommended with an IDE as you have to manage updating your
artifacts yourself, it does not support live reload

$ mvn appengine:run

Overview (`java/demoapp/README.md`)

Demo App: E.164 Formatter

What is this?

The E.164 Formatter is an Android App that reads all the phone numbers stored in
the device's contacts and processes them using the
LibPhoneNumber Library.

The purpose of this App is to show an example of how LPN can be used in a
real-life situation, in this case specifically in an Android App using Java.

How can I install the app?

You can use the source code to build the app yourself.

Where is the LPN code located?

The code using LPN is located in
PhoneNumberFormatting#formatPhoneNumberInApp(PhoneNumberInApp, String, boolean)
.

How does the app work?

On the start screen, the app asks the user for a country to later use when
trying to convert the phone numbers to E.164. After the user starts the process
and grants permission to read and write contacts, the app shows the user two
lists in the UI.

List 1: Formattable

Contains all the phone number that are parsable by LPN, are not short numbers,
and are valid numbers and can be reformatted to E.164 using the country selected
on the start screen. In other words, valid locally formatted phone numbers of
the selected country (e.g. 044 668 18 00 if the selected country is
Switzerland).

Each list item (= one phone number in the device's contacts) has a checkbox.
With the click of the button "Update selected" under the list, the app replaces
the phone numbers of the checked list elements in the contacts with the
suggested E.164 replacements.

List 2: Not formattable

Shows all the phone number that do not fit the criteria of List 1, each tagged
with one of the following errors:

  • Parsing error
  • Short number (e.g. 112)
  • Invalid number (e.g. +41446681800123)
  • Already E.164 (e.g. +41446681800)

Overview (`resources/timezones/README.md`)

Timezone Mapper

The timezone mapper allows a likely timezone to be obtained for a given phone
number. The timezone returned is the canonical ID from CLDR, not a
localised name (or any other identifier). For mobile phones which are associated
with particular area codes, it returns the timezone of the area code; it does
not track the user's current location in any way. This could be used to work out
whether it is likely to be a good time to ring a user based on their provided
number.

Code Location:
java/geocoder/src/com/google/i18n/phonenumbers/PhoneNumberToTimeZonesMapper.java

Example usage:

text
PhoneNumberToTimeZonesMapper timeZonesMapper = PhoneNumberToTimeZonesMapper.getInstance();

List<String> timezones = timeZonesMapper.getTimeZonesForNumber(phoneNumber);

Contributing to the timezone metadata

The timezone metadata is auto-generated with few exceptions, so we cannot accept
pull requests. If we have an error please file an issue and we'll see if we can
make a generic fix.

If making fixes in your own fork while you wait for this, build the metadata by
running this command from the root of the repository (assuming you have ant
installed):

text
ant -f java/build.xml build-timezones-data

Note that, due to our using stable CLDR timezone IDs, we do not change the ID
for an existing timezone when the name of a region or subdivision changes. The
library returns the ID, which you may use to get the localised name from CLDR.

See CLDR's documentation for timezone
translations. You can also
browse different languages'
names; for
example, the Asia/Calcutta timezone identifier has English names
Kolkata Time and India Standard Time, and the English
file links to
a view with
other regions having the same timezone (including those with different IDs).

Other relevant CLDR data:

--- METRICS ---

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →