Android APIs
public class

PhoneNumberUtils

extends Object
java.lang.Object
   ↳ android.telephony.PhoneNumberUtils

Class Overview

Various utilities for dealing with phone number strings.

Summary

Constants
int FORMAT_JAPAN Japanese formatting
int FORMAT_NANP NANP formatting
int FORMAT_UNKNOWN The current locale is unknown, look for a country code or don't format
char PAUSE
int TOA_International
int TOA_Unknown
char WAIT
char WILD
Public Constructors
PhoneNumberUtils()
Public Methods
static String calledPartyBCDFragmentToString(byte[] bytes, int offset, int length)
Like calledPartyBCDToString, but field does not start with a TOA byte.
static String calledPartyBCDToString(byte[] bytes, int offset, int length)
3GPP TS 24.008 10.5.4.7 Called Party BCD Number See Also TS 51.011 10.5.1 "dialing number/ssc string" and TS 11.11 "10.3.1 EF adn (Abbreviated dialing numbers)"
static boolean compare(String a, String b)
Compare phone numbers a and b, return true if they're identical enough for caller ID purposes.
static boolean compare(Context context, String a, String b)
Compare phone numbers a and b, and return true if they're identical enough for caller ID purposes.
static String convertKeypadLettersToDigits(String input)
Translates any alphabetic letters (i.e.
static String extractNetworkPortion(String phoneNumber)
Extracts the network address portion and canonicalizes (filters out separators.) Network address portion is everything up to DTMF control digit separators (pause or wait), but without non-dialable characters.
static String extractPostDialPortion(String phoneNumber)
Extracts the post-dial sequence of DTMF control digits, pauses, and waits.
static void formatJapaneseNumber(Editable text)
This method is deprecated. Use formatNumber(String, String) instead
static void formatNanpNumber(Editable text)
This method is deprecated. Use formatNumber(String, String) instead
static String formatNumber(String source)
This method is deprecated. Use formatNumber(String, String) instead
static String formatNumber(String phoneNumber, String defaultCountryIso)
Format a phone number.
static String formatNumber(String phoneNumber, String phoneNumberE164, String defaultCountryIso)
Format the phone number only if the given number hasn't been formatted.
static void formatNumber(Editable text, int defaultFormattingType)
This method is deprecated. Use formatNumber(String, String) instead
static String formatNumberToE164(String phoneNumber, String defaultCountryIso)
Format the given phoneNumber to the E.164 representation.
static int getFormatTypeForLocale(Locale locale)
This method is deprecated. Use formatNumber(String, String) instead
static String getNumberFromIntent(Intent intent, Context context)
Extracts the phone number from an Intent.
static String getStrippedReversed(String phoneNumber)
Returns the network portion reversed.
final static boolean is12Key(char c)
True if c is ISO-LATIN characters 0-9, *, #
final static boolean isDialable(char c)
True if c is ISO-LATIN characters 0-9, *, # , +, WILD
static boolean isEmergencyNumber(String number)
Checks a given number against the list of emergency numbers provided by the RIL and SIM card.
static boolean isGlobalPhoneNumber(String phoneNumber)
static boolean isISODigit(char c)
True if c is ISO-LATIN characters 0-9
static boolean isLocalEmergencyNumber(Context context, String number)
Checks if a given number is an emergency number for the country that the user is in.
final static boolean isNonSeparator(char c)
True if c is ISO-LATIN characters 0-9, *, # , +, WILD, WAIT, PAUSE
final static boolean isReallyDialable(char c)
True if c is ISO-LATIN characters 0-9, *, # , + (no WILD)
final static boolean isStartsPostDial(char c)
This any anything to the right of this char is part of the post-dial string (eg this is PAUSE or WAIT)
static boolean isVoiceMailNumber(String number)
isVoiceMailNumber: checks a given number against the voicemail number provided by the RIL and SIM card.
static boolean isWellFormedSmsAddress(String address)
Return true iff the network portion of address is, as far as we can tell on the device, suitable for use as an SMS destination address.
static byte[] networkPortionToCalledPartyBCD(String s)
Note: calls extractNetworkPortion(), so do not use for SIM EF[ADN] style records Returns null if network portion is empty.
static byte[] networkPortionToCalledPartyBCDWithLength(String s)
Same as networkPortionToCalledPartyBCD(String), but includes a one-byte length prefix.
static String normalizeNumber(String phoneNumber)
Normalize a phone number by removing the characters other than digits.
static byte[] numberToCalledPartyBCD(String number)
Convert a dialing number to BCD byte array
static String replaceUnicodeDigits(String number)
Replaces all unicode(e.g.
static String stringFromStringAndTOA(String s, int TOA)
Basically: makes sure there's a + in front of a TOA_International number Returns null if s == null
static String stripSeparators(String phoneNumber)
Strips separators from a phone number string.
static String toCallerIDMinMatch(String phoneNumber)
Returns the rightmost MIN_MATCH (5) characters in the network portion in *reversed* order This can be used to do a database lookup against the column that stores getStrippedReversed() Returns null if phoneNumber == null
static int toaFromString(String s)
Returns the TOA for the given dial string Basically, returns TOA_International if there's a + prefix
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final int FORMAT_JAPAN

Added in API level 3

Japanese formatting

Constant Value: 2 (0x00000002)

public static final int FORMAT_NANP

Added in API level 1

NANP formatting

Constant Value: 1 (0x00000001)

public static final int FORMAT_UNKNOWN

Added in API level 1

The current locale is unknown, look for a country code or don't format

Constant Value: 0 (0x00000000)

public static final char PAUSE

Added in API level 1

Constant Value: 44 (0x0000002c)

public static final int TOA_International

Added in API level 1

Constant Value: 145 (0x00000091)

public static final int TOA_Unknown

Added in API level 1

Constant Value: 129 (0x00000081)

public static final char WAIT

Added in API level 1

Constant Value: 59 (0x0000003b)

public static final char WILD

Added in API level 1

Constant Value: 78 (0x0000004e)

Public Constructors

public PhoneNumberUtils ()

Added in API level 1

Public Methods

public static String calledPartyBCDFragmentToString (byte[] bytes, int offset, int length)

Added in API level 1

Like calledPartyBCDToString, but field does not start with a TOA byte. For example: SIM ADN extension fields

public static String calledPartyBCDToString (byte[] bytes, int offset, int length)

Added in API level 1

3GPP TS 24.008 10.5.4.7 Called Party BCD Number See Also TS 51.011 10.5.1 "dialing number/ssc string" and TS 11.11 "10.3.1 EF adn (Abbreviated dialing numbers)"

Parameters
bytes the data buffer
offset should point to the TOA (aka. TON/NPI) octet after the length byte
length is the number of bytes including TOA byte and must be at least 2
Returns
  • partial string on invalid decode FIXME(mkf) support alphanumeric address type currently implemented in SMSMessage.getAddress()

public static boolean compare (String a, String b)

Added in API level 1

Compare phone numbers a and b, return true if they're identical enough for caller ID purposes.

public static boolean compare (Context context, String a, String b)

Added in API level 5

Compare phone numbers a and b, and return true if they're identical enough for caller ID purposes. Checks a resource to determine whether to use a strict or loose comparison algorithm.

public static String convertKeypadLettersToDigits (String input)

Added in API level 1

Translates any alphabetic letters (i.e. [A-Za-z]) in the specified phone number into the equivalent numeric digits, according to the phone keypad letter mapping described in ITU E.161 and ISO/IEC 9995-8.

Returns
  • the input string, with alpha letters converted to numeric digits using the phone keypad letter mapping. For example, an input of "1-800-GOOG-411" will return "1-800-4664-411".

public static String extractNetworkPortion (String phoneNumber)

Added in API level 1

Extracts the network address portion and canonicalizes (filters out separators.) Network address portion is everything up to DTMF control digit separators (pause or wait), but without non-dialable characters. Please note that the GSM wild character is allowed in the result. This must be resolved before dialing. Returns null if phoneNumber == null

public static String extractPostDialPortion (String phoneNumber)

Added in API level 1

Extracts the post-dial sequence of DTMF control digits, pauses, and waits. Strips separators. This string may be empty, but will not be null unless phoneNumber == null. Returns null if phoneNumber == null

public static void formatJapaneseNumber (Editable text)

Added in API level 3

This method is deprecated.
Use formatNumber(String, String) instead

Formats a phone number in-place using the Japanese formatting rules. Numbers will be formatted as:

03-xxxx-xxxx 090-xxxx-xxxx 0120-xxx-xxx +81-3-xxxx-xxxx +81-90-xxxx-xxxx

Parameters
text the number to be formatted, will be modified with the formatting

public static void formatNanpNumber (Editable text)

Added in API level 1

This method is deprecated.
Use formatNumber(String, String) instead

Formats a phone number in-place using the NANP formatting rules. Numbers will be formatted as:

xxxxx xxx-xxxx xxx-xxx-xxxx 1-xxx-xxx-xxxx +1-xxx-xxx-xxxx

Parameters
text the number to be formatted, will be modified with the formatting

public static String formatNumber (String source)

Added in API level 1

This method is deprecated.
Use formatNumber(String, String) instead

Breaks the given number down and formats it according to the rules for the country the number is from.

Parameters
source The phone number to format
Returns
  • A locally acceptable formatting of the input, or the raw input if formatting rules aren't known for the number

public static String formatNumber (String phoneNumber, String defaultCountryIso)

Format a phone number.

If the given number doesn't have the country code, the phone will be formatted to the default country's convention.

Parameters
phoneNumber the number to be formatted.
defaultCountryIso the ISO 3166-1 two letters country code whose convention will be used if the given number doesn't have the country code.
Returns
  • the formatted number, or null if the given number is not valid.

public static String formatNumber (String phoneNumber, String phoneNumberE164, String defaultCountryIso)

Format the phone number only if the given number hasn't been formatted.

The number which has only dailable character is treated as not being formatted.

Parameters
phoneNumber the number to be formatted.
phoneNumberE164 the E164 format number whose country code is used if the given phoneNumber doesn't have the country code.
defaultCountryIso the ISO 3166-1 two letters country code whose convention will be used if the phoneNumberE164 is null or invalid, or if phoneNumber contains IDD.
Returns
  • the formatted number if the given number has been formatted, otherwise, return the given number.

public static void formatNumber (Editable text, int defaultFormattingType)

Added in API level 1

This method is deprecated.
Use formatNumber(String, String) instead

Formats a phone number in-place. Currently FORMAT_JAPAN and FORMAT_NANP is supported as a second argument.

Parameters
text The number to be formatted, will be modified with the formatting
defaultFormattingType The default formatting rules to apply if the number does not begin with +[country_code]

public static String formatNumberToE164 (String phoneNumber, String defaultCountryIso)

Format the given phoneNumber to the E.164 representation.

The given phone number must have an area code and could have a country code.

The defaultCountryIso is used to validate the given number and generate the E.164 phone number if the given number doesn't have a country code.

Parameters
phoneNumber the phone number to format
defaultCountryIso the ISO 3166-1 two letters country code
Returns
  • the E.164 representation, or null if the given phone number is not valid.

public static int getFormatTypeForLocale (Locale locale)

Added in API level 1

This method is deprecated.
Use formatNumber(String, String) instead

Returns the phone number formatting type for the given locale.

Parameters
locale The locale of interest, usually getDefault()
Returns
  • The formatting type for the given locale, or FORMAT_UNKNOWN if the formatting rules are not known for the given locale

public static String getNumberFromIntent (Intent intent, Context context)

Added in API level 1

Extracts the phone number from an Intent.

Parameters
intent the intent to get the number of
context a context to use for database access
Returns
  • the phone number that would be called by the intent, or null if the number cannot be found.

public static String getStrippedReversed (String phoneNumber)

Added in API level 1

Returns the network portion reversed. This string is intended to go into an index column for a database lookup. Returns null if phoneNumber == null

public static final boolean is12Key (char c)

Added in API level 1

True if c is ISO-LATIN characters 0-9, *, #

public static final boolean isDialable (char c)

Added in API level 1

True if c is ISO-LATIN characters 0-9, *, # , +, WILD

public static boolean isEmergencyNumber (String number)

Added in API level 1

Checks a given number against the list of emergency numbers provided by the RIL and SIM card.

Parameters
number the number to look up.
Returns
  • true if the number is in the list of emergency numbers listed in the RIL / SIM, otherwise return false.

public static boolean isGlobalPhoneNumber (String phoneNumber)

Added in API level 1

public static boolean isISODigit (char c)

Added in API level 1

True if c is ISO-LATIN characters 0-9

public static boolean isLocalEmergencyNumber (Context context, String number)

Checks if a given number is an emergency number for the country that the user is in.

Parameters
context the specific context which the number should be checked against
number the number to look up.
Returns
  • true if the specified number is an emergency number for the country the user is currently in.

public static final boolean isNonSeparator (char c)

Added in API level 1

True if c is ISO-LATIN characters 0-9, *, # , +, WILD, WAIT, PAUSE

public static final boolean isReallyDialable (char c)

Added in API level 1

True if c is ISO-LATIN characters 0-9, *, # , + (no WILD)

public static final boolean isStartsPostDial (char c)

Added in API level 1

This any anything to the right of this char is part of the post-dial string (eg this is PAUSE or WAIT)

public static boolean isVoiceMailNumber (String number)

isVoiceMailNumber: checks a given number against the voicemail number provided by the RIL and SIM card. The caller must have the READ_PHONE_STATE credential.

Parameters
number the number to look up.
Returns
  • true if the number is in the list of voicemail. False otherwise, including if the caller does not have the permission to read the VM number.

public static boolean isWellFormedSmsAddress (String address)

Added in API level 1

Return true iff the network portion of address is, as far as we can tell on the device, suitable for use as an SMS destination address.

public static byte[] networkPortionToCalledPartyBCD (String s)

Added in API level 1

Note: calls extractNetworkPortion(), so do not use for SIM EF[ADN] style records Returns null if network portion is empty.

public static byte[] networkPortionToCalledPartyBCDWithLength (String s)

Added in API level 1

Same as networkPortionToCalledPartyBCD(String), but includes a one-byte length prefix.

public static String normalizeNumber (String phoneNumber)

Normalize a phone number by removing the characters other than digits. If the given number has keypad letters, the letters will be converted to digits first.

Parameters
phoneNumber the number to be normalized.
Returns
  • the normalized number.

public static byte[] numberToCalledPartyBCD (String number)

Added in API level 1

Convert a dialing number to BCD byte array

Parameters
number dialing number string if the dialing number starts with '+', set to international TOA
Returns
  • BCD byte array

public static String replaceUnicodeDigits (String number)

Replaces all unicode(e.g. Arabic, Persian) digits with their decimal digit equivalents.

Parameters
number the number to perform the replacement on.
Returns
  • the replaced number.

public static String stringFromStringAndTOA (String s, int TOA)

Added in API level 1

Basically: makes sure there's a + in front of a TOA_International number Returns null if s == null

public static String stripSeparators (String phoneNumber)

Added in API level 1

Strips separators from a phone number string.

Parameters
phoneNumber phone number to strip.
Returns
  • phone string stripped of separators.

public static String toCallerIDMinMatch (String phoneNumber)

Added in API level 1

Returns the rightmost MIN_MATCH (5) characters in the network portion in *reversed* order This can be used to do a database lookup against the column that stores getStrippedReversed() Returns null if phoneNumber == null

public static int toaFromString (String s)

Added in API level 1

Returns the TOA for the given dial string Basically, returns TOA_International if there's a + prefix