1[
2 {
3 "Name": "libphonenumber",
4 "License": "Apache License V2.0",
5 "License File": "LICENSE",
6 "Version Number": "8.12.48",
7 "Upstream URL": "https://github.com/googlei18n/libphonenumber/",
8 "Description": "Google's common Java, C++ and JavaScript library for parsing, formatting, and validating international phone numbers."
9 }
10]
11
12
README.md
1<p align="right">
2<img src="https://travis-ci.org/google/libphonenumber.svg?branch=master">
3</p>
4
5# What is it?
6
7Google's common Java, C++ and JavaScript library for parsing, formatting, and
8validating international phone numbers. The Java version is optimized for
9running on smartphones, and is used by the Android framework since 4.0 (Ice
10Cream Sandwich).
11
12# Quick links
13
14* **Reporting an issue?** Want to send a pull request? See the [contribution
15 guidelines](CONTRIBUTING.md)
16* Check the [frequently asked questions](FAQ.md)
17* Fun! [Falsehoods Programmers Believe About Phone Numbers](FALSEHOODS.md)
18* Look for
19 [`README`s](https://github.com/google/libphonenumber/find/master) in
20 directories relevant to the code you're interested in.
21* For contributors and porters: [How to run the Java demo](run-java-demo.md)
22* For porters: [How to make metadata changes](making-metadata-changes.md)
23
24# Highlights of functionality
25
26* Parsing, formatting, and validating phone numbers for all countries/regions
27 of the world.
28* `getNumberType` - gets the type of the number based on the number itself;
29 able to distinguish Fixed-line, Mobile, Toll-free, Premium Rate, Shared
30 Cost, VoIP, Personal Numbers, UAN, Pager, and Voicemail (whenever feasible).
31* `isNumberMatch` - gets a confidence level on whether two numbers could be
32 the same.
33* `getExampleNumber` and `getExampleNumberForType` - provide valid example
34 numbers for all countries/regions, with the option of specifying which type
35 of example phone number is needed.
36* `isPossibleNumber` - quickly guesses whether a number is a possible
37 phone number by using only the length information, much faster than a full
38 validation.
39* `isValidNumber` - full validation of a phone number for a region using
40 length and prefix information.
41* `AsYouTypeFormatter` - formats phone numbers on-the-fly when users enter
42 each digit.
43* `findNumbers` - finds numbers in text.
44* `PhoneNumberOfflineGeocoder` - provides geographical information related to
45 a phone number.
46* `PhoneNumberToCarrierMapper` - provides carrier information related to a
47 phone number.
48* `PhoneNumberToTimeZonesMapper` - provides timezone information related to a
49 phone number.
50
51# Demo
52
53## Java
54
55The [Java demo](https://libphonenumber.appspot.com/) is updated with a slight
56delay after the GitHub release.
57
58Last demo update: v8.12.47.
59
60If this number is lower than the [latest release's version
61number](https://github.com/google/libphonenumber/releases), we are between
62releases and the demo may be at either version.
63
64## JavaScript
65
66The [JavaScript
67demo](https://htmlpreview.github.io/?https://github.com/google/libphonenumber/blob/master/javascript/i18n/phonenumbers/demo-compiled.html)
68may be run at various tags; this link will take you to `master`.
69
70# Java code
71
72To include the Java code in your application, either integrate with Maven (see
73[wiki](https://github.com/google/libphonenumber/wiki)) or download the latest
74jars from the [Maven
75repository](https://repo1.maven.org/maven2/com/googlecode/libphonenumber/libphonenumber/).
76
77# Javadoc
78
79Javadoc is automatically updated to reflect the latest release at
80https://javadoc.io/doc/com.googlecode.libphonenumber/libphonenumber/.
81
82# Versioning and Announcements
83
84We generally choose the release number following these guidelines.
85
86If any of the changes pushed to master since the last release are incompatible
87with the intent / specification of an existing libphonenumber API or may cause
88libphonenumber (Java, C++, or JS) clients to have to change their code to keep
89building, we publish a major release. For example, if the last release were
907.7.3, the new one would be 8.0.0.
91
92If any of those changes *enable* clients to update their code to take advantage
93of new functionality, and if clients would have to roll-back these changes in
94the event that the release was marked as "bad", we publish a minor release. For
95example, we'd go from 7.7.3 to 7.8.0.
96
97Otherwise, including when a release contains only
98[metadata](FAQ.md#metadata_definition) changes, we publish a sub-minor release,
99e.g. 7.7.3 to 7.7.4.
100
101Sometimes we make internal changes to the code or metadata that, while not
102affecting compatibility for clients, could affect compatibility for **porters**
103of the library. For such changes we make announcements to
104[libphonenumber-discuss](
105https://groups.google.com/forum/#!forum/libphonenumber-discuss). Such changes
106are not reflected in the version number, and we would publish a sub-minor
107release if there were no other changes.
108
109Want to get notified of new releases? During most of the year, excepting
110holidays and extenuating circumstances, we release fortnightly. We update
111[release tags](https://github.com/google/libphonenumber/releases) and
112document detailed [release notes](
113https://github.com/google/libphonenumber/blob/master/release_notes.txt).
114We also send an announcement to [libphonenumber-discuss](
115https://groups.google.com/forum/#!forum/libphonenumber-discuss) for every
116release.
117
118# Quick Examples
119
120Let's say you have a string representing a phone number from Switzerland. This
121is how you parse/normalize it into a `PhoneNumber` object:
122
123```java
124String swissNumberStr = "044 668 18 00";
125PhoneNumberUtil phoneUtil = PhoneNumberUtil.getInstance();
126try {
127 PhoneNumber swissNumberProto = phoneUtil.parse(swissNumberStr, "CH");
128} catch (NumberParseException e) {
129 System.err.println("NumberParseException was thrown: " + e.toString());
130}
131```
132
133At this point, `swissNumberProto` contains:
134
135```json
136{
137 "country_code": 41,
138 "national_number": 446681800
139}
140```
141
142`PhoneNumber` is a class that was originally auto-generated from
143`phonenumber.proto` with necessary modifications for efficiency. For details on
144the meaning of each field, refer to `resources/phonenumber.proto`.
145
146Now let us validate whether the number is valid:
147
148```java
149boolean isValid = phoneUtil.isValidNumber(swissNumberProto); // returns true
150```
151
152There are a few formats supported by the formatting method, as illustrated
153below:
154
155```java
156// Produces "+41 44 668 18 00"
157System.out.println(phoneUtil.format(swissNumberProto, PhoneNumberFormat.INTERNATIONAL));
158// Produces "044 668 18 00"
159System.out.println(phoneUtil.format(swissNumberProto, PhoneNumberFormat.NATIONAL));
160// Produces "+41446681800"
161System.out.println(phoneUtil.format(swissNumberProto, PhoneNumberFormat.E164));
162```
163
164You could also choose to format the number in the way it is dialed from another
165country:
166
167```java
168// Produces "011 41 44 668 1800", the number when it is dialed in the United States.
169System.out.println(phoneUtil.formatOutOfCountryCallingNumber(swissNumberProto, "US"));
170```
171
172## Formatting Phone Numbers 'as you type'
173
174```java
175PhoneNumberUtil phoneUtil = PhoneNumberUtil.getInstance();
176AsYouTypeFormatter formatter = phoneUtil.getAsYouTypeFormatter("US");
177System.out.println(formatter.inputDigit('6')); // Outputs "6"
178... // Input more digits
179System.out.println(formatter.inputDigit('3')); // Now outputs "650 253"
180```
181
182## Geocoding Phone Numbers
183
184```java
185PhoneNumberOfflineGeocoder geocoder = PhoneNumberOfflineGeocoder.getInstance();
186// Outputs "Zurich"
187System.out.println(geocoder.getDescriptionForNumber(swissNumberProto, Locale.ENGLISH));
188// Outputs "Zürich"
189System.out.println(geocoder.getDescriptionForNumber(swissNumberProto, Locale.GERMAN));
190// Outputs "Zurigo"
191System.out.println(geocoder.getDescriptionForNumber(swissNumberProto, Locale.ITALIAN));
192```
193
194## Mapping Phone Numbers to original carriers
195
196Caveat: We do not provide data about the current carrier of a phone number, only
197the original carrier who is assigned the corresponding range. Read about [number
198portability](FAQ.md#what-is-mobile-number-portability).
199
200```java
201PhoneNumber swissMobileNumber =
202 new PhoneNumber().setCountryCode(41).setNationalNumber(798765432L);
203PhoneNumberToCarrierMapper carrierMapper = PhoneNumberToCarrierMapper.getInstance();
204// Outputs "Swisscom"
205System.out.println(carrierMapper.getNameForNumber(swissMobileNumber, Locale.ENGLISH));
206```
207
208More examples on how to use the library can be found in the [unit
209tests](https://github.com/google/libphonenumber/tree/master/java/libphonenumber/test/com/google/i18n/phonenumbers).
210
211# Third-party Ports
212
213Several third-party ports of the phone number library are known to us. We share
214them here in case they're useful for developers.
215
216However, we emphasize that these ports are by developers outside the
217libphonenumber project. We do not evaluate their quality or influence their
218maintenance processes.
219
220* C#: https://github.com/twcclegg/libphonenumber-csharp
221* Go: https://github.com/nyaruka/phonenumbers
222* Objective-c: https://github.com/iziz/libPhoneNumber-iOS
223* PHP: https://github.com/giggsey/libphonenumber-for-php
224* PostgreSQL in-database types: https://github.com/blm768/pg-libphonenumber
225* Python: https://github.com/daviddrysdale/python-phonenumbers
226* Ruby: https://github.com/mobi/telephone_number
227* Rust: https://github.com/1aim/rust-phonenumber
228* Erlang: https://github.com/marinakr/libphonenumber_erlang
229* Clojure: https://github.com/randomseed-io/phone-number
230* R: https://github.com/socialresearchcentre/dialr/
231
232Alternatives to our own versions:
233
234* Android-optimized: Our Java version loads the metadata from
235 `Class#getResourcesAsStream` and asks that Android apps follow the Android
236 loading best practices of repackaging the metadata and loading from
237 `AssetManager#open()` themselves
238 ([FAQ](https://github.com/google/libphonenumber/blob/master/FAQ.md#optimize-loads)).
239 If you don't want to do this, check out the port at
240 https://github.com/MichaelRocks/libphonenumber-android, which does repackage
241 the metadata and use `AssetManager#open()`, and may be depended on without
242 needing those specific loading optimizations from clients. You should also check
243 out the port at https://github.com/lionscribe/libphonenumber-android which also
244 supports geocoding, and only requires a one line code change.
245* Javascript: If you don't want to use our version, which depends on Closure,
246 there are several other options, including
247 https://github.com/catamphetamine/libphonenumber-js - a stripped-down
248 rewrite, about 110 KB in size - and
249 https://github.com/seegno/google-libphonenumber - a browserify-compatible
250 wrapper around the original unmodified library installable via npm, which
251 packs the Google Closure library, about 420 KB in size.
252
