Home

Awesome

What is it?

This is a Dart port of Google's libphonenumber library Google's library for parsing, formatting, and validating international phone numbers.

Highlights of functionality

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.instance;
try {
  PhoneNumber swissNumberProto = phoneUtil.parse(swissNumberStr, "CH");
} on NumberParseException catch (e) {
  print("NumberParseException was thrown: ${e.toString()}");
}

At this point, swissNumberProto contains:

{
  "country_code": 41,
  "national_number": 446681800
}

Now let us validate whether the number is valid:

bool 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"
print(phoneUtil.format(swissNumberProto, PhoneNumberFormat.international));
// Produces "044 668 18 00"
print(phoneUtil.format(swissNumberProto, PhoneNumberFormat.national));
// Produces "+41446681800"
print(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.
print(phoneUtil.formatOutOfCountryCallingNumber(swissNumberProto, "US"));

Formatting Phone Numbers 'as you type'

PhoneNumberUtil phoneUtil = PhoneNumberUtil.instance;
AsYouTypeFormatter formatter = phoneUtil.getAsYouTypeFormatter("US");
print(formatter.inputDigit('6'));  // Outputs "6"
...  // Input more digits
print(formatter.inputDigit('3'));  // Now outputs "650 253"

Extract Phone Numbers From Text

PhoneNumberUtil phoneUtil = PhoneNumberUtil.instance;
Iterable<PhoneNumberMatch> foundNumbers = phoneUtil.findNumbers('Call me on 0241234567/0201234568', 'GH');
print(foundNumbers.elementAt(0)); // Outputs "countryCode: 233, nationalNumber: 241234567"
print(foundNumbers.elementAt(1)); // Outputs "countryCode: 233, nationalNumber: 201234568"

Geocoding Phone Numbers

PhoneNumberOfflineGeocoder geocoder = PhoneNumberOfflineGeocoder.instance;
// Outputs "Zurich"
print(geocoder.getDescriptionForNumber(swissNumberProto, Locale.english));
// Outputs "Zürich"
print(geocoder.getDescriptionForNumber(swissNumberProto, Locale.german));
// Outputs "Zurigo"
print(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 =
      PhoneNumber()..countryCode = 41..nationalNumber = Int64(798765432);
PhoneNumberToCarrierMapper carrierMapper = PhoneNumberToCarrierMapper.instance;
// Outputs "Swisscom"
print(carrierMapper.getNameForNumber(swissMobileNumber, Locale.english));