1[
2 {
3 "Name": "libphonenumber",
4 "License": "Apache License V2.0",
5 "License File": "LICENSE",
6 "Version Number": "8.13.31",
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.13.30.
59
60Note: Even though the library (main branch/[maven release](https://repo1.maven.org/maven2/com/googlecode/libphonenumber/libphonenumber/8.12.56/))
61is at v8.12.57, because of some deployment issues, we were unable to update the
62Java demo with the new binary version. We will soon fix this. Meantime, please
63use JS demo.
64
65If this number is lower than the [latest release's version
66number](https://github.com/google/libphonenumber/releases), we are between
67releases and the demo may be at either version.
68
69### Demo App
70
71There is a demo Android App called [E.164 Formatter](java/demoapp) in this
72repository. The purpose of this App is to show an example of how the library can
73be used in a real-life situation, in this case specifically in an Android App
74using Java.
75
76## JavaScript
77
78The [JavaScript
79demo](https://htmlpreview.github.io/?https://github.com/google/libphonenumber/blob/master/javascript/i18n/phonenumbers/demo-compiled.html)
80may be run at various tags; this link will take you to `master`.
81
82# Java code
83
84To include the Java code in your application, either integrate with Maven (see
85[wiki](https://github.com/google/libphonenumber/wiki)) or download the latest
86jars from the [Maven
87repository](https://repo1.maven.org/maven2/com/googlecode/libphonenumber/libphonenumber/).
88
89# Javadoc
90
91Javadoc is automatically updated to reflect the latest release at
92https://javadoc.io/doc/com.googlecode.libphonenumber/libphonenumber/.
93
94# Versioning and Announcements
95
96We generally choose the release number following these guidelines.
97
98If any of the changes pushed to master since the last release are incompatible
99with the intent / specification of an existing libphonenumber API or may cause
100libphonenumber (Java, C++, or JS) clients to have to change their code to keep
101building, we publish a major release. For example, if the last release were
1027.7.3, the new one would be 8.0.0.
103
104If any of those changes *enable* clients to update their code to take advantage
105of new functionality, and if clients would have to roll-back these changes in
106the event that the release was marked as "bad", we publish a minor release. For
107example, we'd go from 7.7.3 to 7.8.0.
108
109Otherwise, including when a release contains only
110[metadata](FAQ.md#metadata_definition) changes, we publish a sub-minor release,
111e.g. 7.7.3 to 7.7.4.
112
113Sometimes we make internal changes to the code or metadata that, while not
114affecting compatibility for clients, could affect compatibility for **porters**
115of the library. For such changes we make announcements to
116[libphonenumber-discuss](
117https://groups.google.com/forum/#!forum/libphonenumber-discuss). Such changes
118are not reflected in the version number, and we would publish a sub-minor
119release if there were no other changes.
120
121Want to get notified of new releases? During most of the year, excepting
122holidays and extenuating circumstances, we release fortnightly. We update
123[release tags](https://github.com/google/libphonenumber/releases) and
124document detailed [release notes](
125https://github.com/google/libphonenumber/blob/master/release_notes.txt).
126We also send an announcement to [libphonenumber-discuss](
127https://groups.google.com/forum/#!forum/libphonenumber-discuss) for every
128release.
129
130# Quick Examples
131
132Let's say you have a string representing a phone number from Switzerland. This
133is how you parse/normalize it into a `PhoneNumber` object:
134
135```java
136String swissNumberStr = "044 668 18 00";
137PhoneNumberUtil phoneUtil = PhoneNumberUtil.getInstance();
138try {
139 PhoneNumber swissNumberProto = phoneUtil.parse(swissNumberStr, "CH");
140} catch (NumberParseException e) {
141 System.err.println("NumberParseException was thrown: " + e.toString());
142}
143```
144
145At this point, `swissNumberProto` contains:
146
147```json
148{
149 "country_code": 41,
150 "national_number": 446681800
151}
152```
153
154`PhoneNumber` is a class that was originally auto-generated from
155`phonenumber.proto` with necessary modifications for efficiency. For details on
156the meaning of each field, refer to `resources/phonenumber.proto`.
157
158Now let us validate whether the number is valid:
159
160```java
161boolean isValid = phoneUtil.isValidNumber(swissNumberProto); // returns true
162```
163
164There are a few formats supported by the formatting method, as illustrated
165below:
166
167```java
168// Produces "+41 44 668 18 00"
169System.out.println(phoneUtil.format(swissNumberProto, PhoneNumberFormat.INTERNATIONAL));
170// Produces "044 668 18 00"
171System.out.println(phoneUtil.format(swissNumberProto, PhoneNumberFormat.NATIONAL));
172// Produces "+41446681800"
173System.out.println(phoneUtil.format(swissNumberProto, PhoneNumberFormat.E164));
174```
175
176You could also choose to format the number in the way it is dialed from another
177country:
178
179```java
180// Produces "011 41 44 668 1800", the number when it is dialed in the United States.
181System.out.println(phoneUtil.formatOutOfCountryCallingNumber(swissNumberProto, "US"));
182```
183
184## Formatting Phone Numbers 'as you type'
185
186```java
187PhoneNumberUtil phoneUtil = PhoneNumberUtil.getInstance();
188AsYouTypeFormatter formatter = phoneUtil.getAsYouTypeFormatter("US");
189System.out.println(formatter.inputDigit('6')); // Outputs "6"
190... // Input more digits
191System.out.println(formatter.inputDigit('3')); // Now outputs "650 253"
192```
193
194## Geocoding Phone Numbers
195
196```java
197PhoneNumberOfflineGeocoder geocoder = PhoneNumberOfflineGeocoder.getInstance();
198// Outputs "Zurich"
199System.out.println(geocoder.getDescriptionForNumber(swissNumberProto, Locale.ENGLISH));
200// Outputs "Zürich"
201System.out.println(geocoder.getDescriptionForNumber(swissNumberProto, Locale.GERMAN));
202// Outputs "Zurigo"
203System.out.println(geocoder.getDescriptionForNumber(swissNumberProto, Locale.ITALIAN));
204```
205
206## Mapping Phone Numbers to original carriers
207
208Caveat: We do not provide data about the current carrier of a phone number, only
209the original carrier who is assigned the corresponding range. Read about [number
210portability](FAQ.md#what-is-mobile-number-portability).
211
212```java
213PhoneNumber swissMobileNumber =
214 new PhoneNumber().setCountryCode(41).setNationalNumber(798765432L);
215PhoneNumberToCarrierMapper carrierMapper = PhoneNumberToCarrierMapper.getInstance();
216// Outputs "Swisscom"
217System.out.println(carrierMapper.getNameForNumber(swissMobileNumber, Locale.ENGLISH));
218```
219
220More examples on how to use the library can be found in the [unit
221tests](https://github.com/google/libphonenumber/tree/master/java/libphonenumber/test/com/google/i18n/phonenumbers).
222
223# Third-party Ports
224
225Several third-party ports of the phone number library are known to us. We share
226them here in case they're useful for developers.
227
228However, we emphasize that these ports are by developers outside the
229libphonenumber project. We do not evaluate their quality or influence their
230maintenance processes.
231
232* C#: https://github.com/twcclegg/libphonenumber-csharp
233* Gleam: https://github.com/massivefermion/phony
234* Go: https://github.com/nyaruka/phonenumbers
235* Objective-c: https://github.com/iziz/libPhoneNumber-iOS
236* Swift: https://github.com/marmelroy/PhoneNumberKit
237* PHP: https://github.com/giggsey/libphonenumber-for-php
238* PostgreSQL in-database types: https://github.com/blm768/pg-libphonenumber
239* Python: https://github.com/daviddrysdale/python-phonenumbers
240* Ruby: https://github.com/ianks/mini_phone
241* Ruby: https://github.com/daddyz/phonelib
242* Ruby: https://github.com/mobi/telephone_number
243* Rust: https://github.com/1aim/rust-phonenumber
244* Erlang: https://github.com/marinakr/libphonenumber_erlang
245* Clojure: https://github.com/randomseed-io/phone-number
246* R: https://github.com/socialresearchcentre/dialr/
247* Elixir: https://github.com/socialpaymentsbv/ex_phone_number
248* Salesforce: https://appexchange.salesforce.com/appxListingDetail?listingId=a0N3A00000G12oJUAR
249
250Alternatives to our own versions:
251
252* Android-optimized: Our Java version loads the metadata from
253 `Class#getResourcesAsStream` and asks that Android apps follow the Android
254 loading best practices of repackaging the metadata and loading from
255 `AssetManager#open()` themselves
256 ([FAQ](https://github.com/google/libphonenumber/blob/master/FAQ.md#optimize-loads)).
257 If you don't want to do this, check out the port at
258 https://github.com/MichaelRocks/libphonenumber-android, which does repackage
259 the metadata and use `AssetManager#open()`, and may be depended on without
260 needing those specific loading optimizations from clients. You should also check
261 out the port at https://github.com/lionscribe/libphonenumber-android which also
262 supports geocoding, and only requires a one line code change.
263* Javascript: If you don't want to use our version, which depends on Closure,
264 there are several other options, including
265 https://github.com/catamphetamine/libphonenumber-js - a stripped-down
266 rewrite, about 110 KB in size - and
267 https://github.com/seegno/google-libphonenumber - a browserify-compatible
268 wrapper around the original unmodified library installable via npm, which
269 packs the Google Closure library, about 420 KB in size.
270
271Tools based on libphonenumber metadata:
272
273* Scala: https://github.com/mr-tolmach/raf - library for generating valid phone numbers in the E.164 format
274
