README.md

   1 # What is it?
   2
   3 Google's common Java, C++ and JavaScript library for parsing, formatting, storing 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).
   4
   5 # Highlights of functionality
   6   * Parsing/formatting/validating phone numbers for all countries/regions of the world.
   7   * 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 and Personal Numbers  (whenever feasible).
   8   * isNumberMatch - gets a confidence level on whether two numbers could be the same.
   9   * getExampleNumber/getExampleNumberByType - provides valid example numbers for all countries/regions, with the option of specifying which type of example phone number is needed.
  10   * isPossibleNumber - quickly guessing whether a number is a possible phonenumber by using only the length information, much faster than a full validation.
  11   * isValidNumber - full validation of a phone number for a region using length and prefix information.
  12   * ` AsYouTypeFormatter ` - formats phone numbers on-the-fly when users enter each digit.
  13   * findNumbers - finds numbers in text input.
  14   * ` PhoneNumberOfflineGeocoder ` - provides geographical information related to a phone number.
  15   * ` PhoneNumberToCarrierMapper ` - provides carrier information related to a phone number.
  16
  17 # Demo (v7.0.4)
  18 [Java](http://libphonenumber.appspot.com/)
  19
  20 [JavaScript](https://rawgit.com/googlei18n/libphonenumber/master/javascript/i18n/phonenumbers/demo-compiled.html)
  21
  22 # Code
  23 To include the code in your application, either integrate with Maven or download the latest Jars from the Maven repository:
  24
  25 http://repo1.maven.org/maven2/com/googlecode/libphonenumber/libphonenumber/
  26
  27 # Quick Examples
  28 Let's say you have a string representing a phone number from Switzerland. This is how you parse/normalize it into a ` PhoneNumber ` object:
  29 ```
  30 String swissNumberStr = "044 668 18 00"
  31 PhoneNumberUtil phoneUtil = PhoneNumberUtil.getInstance();
  32 try {
  33   PhoneNumber swissNumberProto = phoneUtil.parse(swissNumberStr, "CH");
  34 } catch (NumberParseException e) {
  35   System.err.println("NumberParseException was thrown: " + e.toString());
  36 }
  37 ```
  38
  39 At this point, swissNumberProto contains:
  40 ```
  41 {
  42 country_code: 41
  43 national_number: 446681800
  44 }
  45 ```
  46
  47 ` PhoneNumber ` is a class that is auto-generated from the phonenumber.proto with necessary modifications for efficiency. For details on the meaning of each field, refer to https://github.com/googlei18n/test/blob/master/resources/phonenumber.proto
  48
  49 Now let us validate whether the number is valid:
  50 ```
  51 boolean isValid = phoneUtil.isValidNumber(swissNumberProto); // returns true
  52 ```
  53
  54 There are a few formats supported by the formatting method, as illustrated below:
  55 ```
  56 // Produces "+41 44 668 18 00"
  57 System.out.println(phoneUtil.format(swissNumberProto, PhoneNumberFormat.INTERNATIONAL));
  58 // Produces "044 668 18 00"
  59 System.out.println(phoneUtil.format(swissNumberProto, PhoneNumberFormat.NATIONAL));
  60 // Produces "+41446681800"
  61 System.out.println(phoneUtil.format(swissNumberProto, PhoneNumberFormat.E164));
  62 ```
  63
  64 You could also choose to format the number in the way it is dialed from another country:
  65
  66 ```
  67 // Produces "011 41 44 668 1800", the number when it is dialed in the United States.
  68 System.out.println(phoneUtil.formatOutOfCountryCallingNumber(swissNumberProto, "US"));
  69 ```
  70
  71 ### Formatting Phone Numbers 'as you type'
  72 ```
  73 PhoneNumberUtil phoneUtil = PhoneNumberUtil.getInstance();
  74 AsYouTypeFormatter formatter = phoneUtil.getAsYouTypeFormatter("US");
  75 System.out.println(formatter.inputDigit('6'));  // Outputs "6"
  76 ...  // Input more digits
  77 System.out.println(formatter.inputDigit('3'));  // Now outputs "650 253"
  78 ```
  79
  80 ### Geocoding Phone Numbers offline
  81 ```
  82 PhoneNumberOfflineGeocoder geocoder = PhoneNumberOfflineGeocoder.getInstance();
  83 // Outputs "Zurich"
  84 System.out.println(geocoder.getDescriptionForNumber(swissNumberProto, Locale.ENGLISH));
  85 // Outputs "Zürich"
  86 System.out.println(geocoder.getDescriptionForNumber(swissNumberProto, Locale.GERMAN));
  87 // Outputs "Zurigo"
  88 System.out.println(geocoder.getDescriptionForNumber(swissNumberProto, Locale.ITALIAN));
  89 ```
  90
  91 ### Mapping Phone Numbers to carrier
  92 ```
  93 PhoneNumber swissMobileNumber =
  94     new PhoneNumber().setCountryCode(41).setNationalNumber(798765432L);
  95 PhoneNumberToCarrierMapper carrierMapper = PhoneNumberToCarrierMapper.getInstance();
  96 // Outputs "Swisscom"
  97 System.out.println(carrierMapper.getNameForNumber(swissMobileNumber, Locale.ENGLISH));
  98 ```
  99
 100
 101 ---
 102
 103
 104 More examples on how to use the library can be found in the unittests at https://github.com/googlei18n/test/tree/master/java/libphonenumber/test/com/google/i18n/phonenumbers
 105
 106 # Known Ports
 107 Several people are porting the phone number library to other languages. Here are some we know about. Note that they are done on voluntary basis by developers outside our project, so we cannot guarantee their quality.
 108   * C#: https://github.com/erezak/libphonenumber-csharp
 109   * objective-c: https://github.com/iziz/libPhoneNumber-iOS
 110   * Python: https://github.com/daviddrysdale/python-phonenumbers
 111   * Ruby: https://github.com/sstephenson/global_phone
 112   * PHP: https://github.com/giggsey/libphonenumber-for-php