Using libphonenumber for Phone Number Validation and Conversion

1. Overview

In this quick tutorial, we’ll see how to use Google’s open-source library libphonenumber to validate phone numbers in Java.

2. Maven Dependency

First, we’ll need to add the dependency for this library in our pom.xml:

<dependency>
    <groupId>com.googlecode.libphonenumber</groupId>
    <artifactId>libphonenumber</artifactId>
    <version>8.12.10</version>
</dependency>

The latest version information can be found over on Maven Central.

Now, we’re equipped to use all the functionality this library has to offer.

3. PhoneNumberUtil

The library provides a utility class, PhoneNumberUtil, which provides several methods to play around with phone numbers.

Let’s see a few examples of how we can use its various APIs for validation.

Importantly, in all examples, we’ll be using the singleton object of this class to make method calls:

PhoneNumberUtil phoneNumberUtil = PhoneNumberUtil.getInstance();

3.1. isPossibleNumber

Using PhoneNumberUtil#isPossibleNumber, we can check if a given number is possible for a particular country code or region.

As an example, let’s take the United States, which has a country code of 1. We can check if given phone numbers are possible US numbers in this fashion:

@Test
public void givenPhoneNumber_whenPossible_thenValid() {
    PhoneNumber number = new PhoneNumber();
    number.setCountryCode(1).setNationalNumber(123000L);
    assertFalse(phoneNumberUtil.isPossibleNumber(number));
    assertFalse(phoneNumberUtil.isPossibleNumber("+1 343 253 00000", "US"));
    assertFalse(phoneNumberUtil.isPossibleNumber("(343) 253-00000", "US"));
    assertFalse(phoneNumberUtil.isPossibleNumber("dial p for pizza", "US"));
    assertFalse(phoneNumberUtil.isPossibleNumber("123-000", "US"));
}

Here, we used another variant of this function as well by passing in the region that we’re expecting the number to be dialed from as a String.

3.2. isPossibleNumberForType

The library recognizes different types of phone numbers, such as fixed-line, mobile, toll-free, voicemail, VoIP, pager, and many more.

Its utility method isPossibleNumberForType checks if the given number is possible for a given type in a particular region.

As an example, let’s go for Argentina since it allows for different possible lengths of numbers for different types.

Hence, we can use it to demonstrate the capability of this API:

@Test
public void givenPhoneNumber_whenPossibleForType_thenValid() {
    PhoneNumber number = new PhoneNumber();
    number.setCountryCode(54);

    number.setNationalNumber(123456);
    assertTrue(phoneNumberUtil.isPossibleNumberForType(number, PhoneNumberType.FIXED_LINE));
    assertFalse(phoneNumberUtil.isPossibleNumberForType(number, PhoneNumberType.TOLL_FREE));

    number.setNationalNumber(12345678901L);
    assertFalse(phoneNumberUtil.isPossibleNumberForType(number, PhoneNumberType.FIXED_LINE));
    assertTrue(phoneNumberUtil.isPossibleNumberForType(number, PhoneNumberType.MOBILE));
    assertFalse(phoneNumberUtil.isPossibleNumberForType(number, PhoneNumberType.TOLL_FREE));
}

As we can see, the above code validates that Argentina permits 6-digit fixed line numbers and 11-digit mobile numbers.

3.3. isAlphaNumber

This method is used to verify if the given phone number is a valid alphanumeric one, such as 325-CARS:

@Test
public void givenPhoneNumber_whenAlphaNumber_thenValid() {
    assertTrue(phoneNumberUtil.isAlphaNumber("325-CARS"));
    assertTrue(phoneNumberUtil.isAlphaNumber("0800 REPAIR"));
    assertTrue(phoneNumberUtil.isAlphaNumber("1-800-MY-APPLE"));
    assertTrue(phoneNumberUtil.isAlphaNumber("1-800-MY-APPLE.."));
    assertFalse(phoneNumberUtil.isAlphaNumber("+876 1234-1234"));
}

To clarify, a valid alpha number contains at least three digits at the beginning, followed by three or more alphabet letters. The utility method above first strips the given input off any formatting and then checks for this condition.

3.4. isValidNumber

The previous API we discussed quickly checks the phone number on the basis of its length only. On the other hand, isValidNumber does a complete validation using prefix as well as length information:

@Test
public void givenPhoneNumber_whenValid_thenOK() throws Exception {

    PhoneNumber phone = phoneNumberUtil.parse("+911234567890", 
      CountryCodeSource.UNSPECIFIED.name());

    assertTrue(phoneNumberUtil.isValidNumber(phone));
    assertTrue(phoneNumberUtil.isValidNumberForRegion(phone, "IN"));
    assertFalse(phoneNumberUtil.isValidNumberForRegion(phone, "US"));
    assertTrue(phoneNumberUtil.isValidNumber(phoneNumberUtil.getExampleNumber("IN")));
}

Here, the number is validated when we did not specify a region, and also when we did.

3.5. isNumberGeographical​

This method checks if a given number has geography or region associated with it:

@Test
public void givenPhoneNumber_whenNumberGeographical_thenValid() throws NumberParseException {
    
    PhoneNumber phone = phoneNumberUtil.parse("+911234567890", "IN");
    assertTrue(phoneNumberUtil.isNumberGeographical(phone));

    phone = new PhoneNumber().setCountryCode(1).setNationalNumber(2530000L);
    assertFalse(phoneNumberUtil.isNumberGeographical(phone));

    phone = new PhoneNumber().setCountryCode(800).setNationalNumber(12345678L);
    assertFalse(phoneNumberUtil.isNumberGeographical(phone));
}

Here, in the first assert above, we gave the phone number in an international format with the region code, and the method returned true. The second assert uses a local number from the USA, and the third one a toll-free number. So the API returned false for these two.

4. Converting Phone Numbers into International Format (E.164)

Another common use case is converting a phone number into the E.164 international format, which is the globally recognized standard for representing phone numbers. In this format, a number includes the country calling code followed by the subscriber number, without any additional formatting symbols such as spaces, parentheses, or dashes.

For example, a U.S. number written as (415) 555-2671 would be represented as +14155552671 in E.164 format.

The PhoneNumberUtil class provides a convenient method to perform this conversion using its format() API. To do this, we first parse the number using the parse() method, providing the local region as context, and then format it using PhoneNumberFormat.E164 as the desired output format:

@Test
public void givenUSPhoneNumber_whenFormattedToE164_thenReturnsCorrectInternationalFormat() throws NumberParseException {
    PhoneNumberUtil phoneNumberUtil = PhoneNumberUtil.getInstance();

    PhoneNumber number = phoneNumberUtil.parse("(415) 555-2671", "US");
    String e164Format = phoneNumberUtil.format(number, PhoneNumberUtil.PhoneNumberFormat.E164);

    assertEquals("+14155552671", e164Format);
}

In the example above, we first parse a U.S. local phone number by specifying the region code “US”. The library then interprets the number correctly and, when formatted using the E164 option, returns the normalized international version that includes the +1 country prefix and removes all local formatting.

The same approach can be applied to numbers from other countries. For instance, if we take an Indian mobile number such as 09876543210, we can parse it with the region code “IN” and convert it to the proper international format as shown below:

@Test
public void givenIndianPhoneNumber_whenFormattedToE164_thenReturnsCorrectInternationalFormat() throws NumberParseException {
    PhoneNumberUtil phoneNumberUtil = PhoneNumberUtil.getInstance();

    PhoneNumber number = phoneNumberUtil.parse("09876543210", "IN");
    String e164Format = phoneNumberUtil.format(number, PhoneNumberUtil.PhoneNumberFormat.E164);

    assertEquals("+919876543210", e164Format);
}

In this case, the library automatically recognizes that the number belongs to India, adds the country code +91, and removes any unnecessary leading zeros or separators. The final result strictly follows the E.164 format, which makes it ideal for use in systems that handle international communication.

Converting phone numbers into E.164 format is handy when storing phone numbers in a database or when working with APIs that require globally standardized formats, such as SMS gateways or telephony services. It ensures that every number is stored in a consistent, unambiguous form, regardless of the country or the end user’s input style.

5. Conclusion

In this tutorial, we saw some of the functionality offered by libphonenumber to format and validate phone numbers using code samples.

This is a rich library that offers many more utility functions and takes care of most of our application needs for formatting, parsing, and validating phone numbers.