libphonenumber README

The project's README from github.com/google/libphonenumber. As one markdown file: 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).

Quick links

Highlights of functionality

Demo

Java

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

Last demo update: v9.0.39.

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:

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:

{
  "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:

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

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

// 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:

// 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'

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

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.

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:

Tools based on libphonenumber metadata:

libphonenumber (google/libphonenumber)

Searching Database…

18.3K ·GitHub
Libphonenumber
Что это такое?Библиотека от Google для разбора, форматирования и проверки международных телефонных номеров; доступна на Java, C++ и JavaScript.
Это библиотека, которую я встраиваю в проект, или самостоятельное приложение?Это библиотека, которую вы добавляете в свой проект на Java, C++ или JavaScript; в комплекте есть демонстрационное Android-приложение и JS-демо для знакомства с ней, но сама по себе это не инструмент для конечных пользователей.
Как добавить её в свой проект?Для Java подключите через Maven или скачайте последние jar-файлы из Maven-репозитория; сборки для C++ и JS создаются из исходных каталогов этого репозитория.
Нужно ли версии на JS что-то дополнительно?Официальная версия для JS зависит от Google Closure; если эта зависимость вам не нужна, есть сторонние альтернативы — например, урезанная переписанная версия или npm-обёртка, совместимая с browserify.
Скажет ли она, какой оператор связи сейчас обслуживает номер?Нет — определение оператора возвращает только того оператора, которому изначально был выделен этот диапазон номеров, а не того, кто владеет номером сейчас, из-за переносимости номеров.
Java-версия настроена специально под Android?Да, Java-версия оптимизирована для смартфонов и используется Android-фреймворком начиная с Android 4.0 (Ice Cream Sandwich); Android-приложениям предполагается переупаковывать метаданные и загружать их через AssetManager или использовать стороннюю портированную версию, которая уже это делает.
Может ли она узнать личные данные владельца телефона?Нет — она работает только с самим номером и выдаёт геолокацию, оператора и часовой пояс; она не определяет самого человека или нынешнего владельца.
Что библиотека на самом деле может сказать мне о номере?Она умеет разбирать и форматировать номера, проверять, настоящие ли они, определять их тип (мобильный, бесплатный, VoIP и т. д.), находить номера внутри текста, форматировать номер на лету по мере ввода пользователем, а также офлайн определять геолокацию, оператора и часовой пояс.
Есть ли порты для других языков, например Python или Go?Да, есть сторонние порты для C#, Go, Python, Ruby, Rust, PHP, Swift, Objective-C, Elixir, Dart, R, Clojure, Erlang и других языков, но Google их не поддерживает и не проверяет.
Как часто обновляются метаданные телефонных номеров?Проект обычно выпускает обновления раз в две недели; номер версии меняется в зависимости от того, ломают ли изменения совместимость, добавляют ли функциональность или затрагивают только метаданные: мажорная, минорная или мелкая версия.
Есть ли более легковесная альтернатива на JS, если мне не нужна зависимость Closure?Да, есть варианты от сообщества: урезанная переписанная версия размером около 110 КБ и npm-обёртка, совместимая с browserify (около 420 КБ), над оригинальной библиотекой на основе Closure.
What are similar projects?tink, protobuf, Android-Universal-Image-Loader, PermissionsDispatcher, timber, incubator-weex, chat, grpc
Which topics is it in?phone-number, parsing, validation, telegram, nlp, sdk, c++, java, mobile, android, api, apache-2.0
Creator
google
Size
318.3 MB
Stars
18.3K
Updated
CommitOct 08Releasev9.0.41Oct 08
Age
11y
Commits · 90 Days