phonenumbers

func CanBeInternationallyDialled ¶

func CanBeInternationallyDialled(number *PhoneNumber) bool

Returns true if the number can be dialled from outside the region, or unknown. If the number can only be dialled from within the region, returns false. Does not check the number is a valid number. Note that, at the moment, this method does not handle short numbers (which are currently all presumed to not be diallable from outside their country).

func ConnectsToEmergencyNumber ¶

func ConnectsToEmergencyNumber(number string, regionCode string) bool

Returns true if the given number, exactly as dialed, might be used to connect to an emergency service in the given region.

This method accepts a string, rather than a PhoneNumber, because it needs to distinguish cases such as "+1 911" and "911", where the former may not connect to an emergency service in all cases but the latter would. This method takes into account cases where the number might contain formatting, or might have additional digits appended (when it is okay to do that in the specified region).

number: the phone number to test regionCode: the region where the phone number is being dialed return: whether the number might be used to connect to an emergency service in the given region

func ConvertAlphaCharactersInNumber ¶

func ConvertAlphaCharactersInNumber(number string) string

Converts all alpha characters in a number to their respective digits on a keypad, but retains existing formatting.

func FindNumbers ¶

func FindNumbers(text, defaultRegion string) iter.Seq[*PhoneNumberMatch]

FindNumbers returns an iterator over all phone-number matches in text. It is a shortcut for FindNumbersWithLeniency with VALID leniency and no limit on the number of invalid candidates tried. defaultRegion is the region to assume for numbers not written in international format; pass "" or "ZZ" to only consider numbers with a leading plus.

Range over the result with for/range:

for m := range phonenumbers.FindNumbers(text, "US") {
	fmt.Println(m.RawString(), m.Start(), m.End())
}

func FindNumbersWithLeniency ¶

func FindNumbersWithLeniency(text, defaultRegion string, leniency Leniency, maxTries int) iter.Seq[*PhoneNumberMatch]

FindNumbersWithLeniency returns an iterator over all phone-number matches in text at the given leniency. maxTries caps the number of invalid candidates tried before giving up, to bound degenerate inputs with many false positives (use math.MaxInt for no practical limit). Must be >= 0.

func Format ¶

func Format(number *PhoneNumber, numberFormat PhoneNumberFormat) string

Formats a phone number in the specified format using default rules. Note that this does not promise to produce a phone number that the user can dial from where they are - although we do format in either 'national' or 'international' format depending on what the client asks for, we do not currently support a more abbreviated format, such as for users in the same "area" who could potentially dial the number without area code. Note that if the phone number has a country calling code of 0 or an otherwise invalid country calling code, we cannot work out which formatting rules to apply so we return the national significant number with no formatting applied.

func FormatByPattern ¶

func FormatByPattern(number *PhoneNumber,
	numberFormat PhoneNumberFormat,
	userDefinedFormats []*NumberFormat) string

FormatByPattern formats a phone number in the specified format using client-defined formatting rules. Note that if the phone number has a country calling code of zero or an otherwise invalid country calling code, we cannot work out things like whether there should be a national prefix applied, or how to format extensions, so we return the national significant number with no formatting applied.

func FormatInOriginalFormat ¶

func FormatInOriginalFormat(number *PhoneNumber, regionCallingFrom string) string

Formats a phone number using the original phone number format that the number is parsed from. The original format is embedded in the country_code_source field of the PhoneNumber object passed in. If such information is missing, the number will be formatted into the NATIONAL format by default. When the number contains a leading zero and this is unexpected for this country, or we don't have a formatting pattern for the number, the method returns the raw input when it is available.

Note this method guarantees no digit will be inserted, removed or modified as a result of formatting.

func FormatNationalNumberWithCarrierCode ¶

func FormatNationalNumberWithCarrierCode(number *PhoneNumber, carrierCode string) string

Formats a phone number in national format for dialing using the carrier as specified in the carrierCode. The carrierCode will always be used regardless of whether the phone number already has a preferred domestic carrier code stored. If carrierCode contains an empty string, returns the number in national format without any carrier code.

func FormatNationalNumberWithPreferredCarrierCode ¶

func FormatNationalNumberWithPreferredCarrierCode(
	number *PhoneNumber,
	fallbackCarrierCode string) string

Formats a phone number in national format for dialing using the carrier as specified in the preferredDomesticCarrierCode field of the PhoneNumber object passed in. If that is missing, use the fallbackCarrierCode passed in instead. If there is no preferredDomesticCarrierCode, and the fallbackCarrierCode contains an empty string, return the number in national format without any carrier code.

Use formatNationalNumberWithCarrierCode instead if the carrier code passed in should take precedence over the number's preferredDomesticCarrierCode when formatting.

func FormatNumberForMobileDialing ¶

func FormatNumberForMobileDialing(
	number *PhoneNumber,
	regionCallingFrom string,
	withFormatting bool) string

Returns a number formatted in such a way that it can be dialed from a mobile phone in a specific region. If the number cannot be reached from the region (e.g. some countries block toll-free numbers from being called outside of the country), the method returns an empty string.

func FormatOutOfCountryCallingNumber ¶

func FormatOutOfCountryCallingNumber(
	number *PhoneNumber,
	regionCallingFrom string) string

Formats a phone number for out-of-country dialing purposes. If no regionCallingFrom is supplied, we format the number in its INTERNATIONAL format. If the country calling code is the same as that of the region where the number is from, then NATIONAL formatting will be applied.

If the number itself has a country calling code of zero or an otherwise invalid country calling code, then we return the number with no formatting applied.

Note this function takes care of the case for calling inside of NANPA and between Russia and Kazakhstan (who share the same country calling code). In those cases, no international prefix is used. For regions which have multiple international prefixes, the number in its INTERNATIONAL format will be returned instead.

func FormatOutOfCountryKeepingAlphaChars ¶

func FormatOutOfCountryKeepingAlphaChars(
	number *PhoneNumber,
	regionCallingFrom string) string

Formats a phone number for out-of-country dialing purposes.

Note that in this version, if the number was entered originally using alpha characters and this version of the number is stored in raw_input, this representation of the number will be used rather than the digit representation. Grouping information, as specified by characters such as "-" and " ", will be retained.

Caveats:

• This will not produce good results if the country calling code is both present in the raw input _and_ is the start of the national number. This is not a problem in the regions which typically use alpha numbers.
• This will also not produce good results if the raw input has any grouping information within the first three digits of the national number, and if the function needs to strip preceding digits/words in the raw input before these digits. Normally people group the first three digits together so this is not a huge problem - and will be fixed if it proves to be so.

func GetCountryCodeForRegion ¶

func GetCountryCodeForRegion(regionCode string) int

Returns the country calling code for a specific region. For example, this would be 1 for the United States, and 64 for New Zealand.

func GetCountryMobileToken ¶

func GetCountryMobileToken(countryCallingCode int) string

Returns the mobile token for the provided country calling code if it has one, otherwise returns an empty string. A mobile token is a number inserted before the area code when dialing a mobile number from that country from abroad.

func GetLengthOfGeographicalAreaCode ¶

func GetLengthOfGeographicalAreaCode(number *PhoneNumber) int

Gets the length of the geographical area code from the PhoneNumber object passed in, so that clients could use it to split a national significant number into geographical area code and subscriber number. It works in such a way that the resultant subscriber number should be diallable, at least on some devices. An example of how this could be used:

number, err := Parse("16502530000", "US")
// ... deal with err appropriately ...
nationalSignificantNumber := GetNationalSignificantNumber(number)
var areaCode, subscriberNumber string

areaCodeLength := GetLengthOfGeographicalAreaCode(number)
if areaCodeLength > 0 {
	areaCode = nationalSignificantNumber[0:areaCodeLength]
	subscriberNumber = nationalSignificantNumber[areaCodeLength:]
} else {
	areaCode = ""
	subscriberNumber = nationalSignificantNumber
}

N.B.: area code is a very ambiguous concept, so the I18N team generally recommends against using it for most purposes, but recommends using the more general national_number instead. Read the following carefully before deciding to use this method:

• geographical area codes change over time, and this method honors those changes; therefore, it doesn't guarantee the stability of the result it produces.
• subscriber numbers may not be diallable from all devices (notably mobile devices, which typically requires the full national_number to be dialled in most regions).
• most non-geographical numbers have no area codes, including numbers from non-geographical entities
• some geographical numbers have no area codes.

func GetLengthOfNationalDestinationCode ¶

func GetLengthOfNationalDestinationCode(number *PhoneNumber) int

Gets the length of the national destination code (NDC) from the PhoneNumber object passed in, so that clients could use it to split a national significant number into NDC and subscriber number. The NDC of a phone number is normally the first group of digit(s) right after the country calling code when the number is formatted in the international format, if there is a subscriber number part that follows. An example of how this could be used:

number, err := Parse("18002530000", "US")
// ... deal with err appropriately ...
nationalSignificantNumber := GetNationalSignificantNumber(number)
var nationalDestinationCode, subscriberNumber string

nationalDestinationCodeLength := GetLengthOfNationalDestinationCode(number)
if nationalDestinationCodeLength > 0 {
	nationalDestinationCode = nationalSignificantNumber[0:nationalDestinationCodeLength]
	subscriberNumber = nationalSignificantNumber[nationalDestinationCodeLength:]
} else {
	nationalDestinationCode = ""
	subscriberNumber = nationalSignificantNumber
}

Refer to the unittests to see the difference between this function and GetLengthOfGeographicalAreaCode().

func GetNationalSignificantNumber ¶

func GetNationalSignificantNumber(number *PhoneNumber) string

Gets the national significant number of the a phone number. Note a national significant number doesn't contain a national prefix or any formatting.

func GetNddPrefixForRegion ¶

func GetNddPrefixForRegion(regionCode string, stripNonDigits bool) string

Returns the national dialling prefix for a specific region. For example, this would be 1 for the United States, and 0 for New Zealand. Set stripNonDigits to true to strip symbols like "~" (which indicates a wait for a dialling tone) from the prefix returned. If no national prefix is present, we return null.

Warning: Do not use this method for do-your-own formatting - for some regions, the national dialling prefix is used only for certain types of numbers. Use the library's formatting functions to prefix the national prefix when required.

func GetRegionCodeForCountryCode ¶

func GetRegionCodeForCountryCode(countryCallingCode int) string

Returns the region code that matches the specific country calling code. In the case of no region code being found, ZZ will be returned. In the case of multiple regions, the one designated in the metadata as the "main" region for this calling code will be returned. If the countryCallingCode entered is valid but doesn't match a specific region (such as in the case of non-geographical calling codes like 800) the value "001" will be returned (corresponding to the value for World in the UN M.49 schema).

func GetRegionCodeForNumber ¶

func GetRegionCodeForNumber(number *PhoneNumber) string

Returns the region where a phone number is from. This could be used for geocoding at the region level.

func GetRegionCodesForCountryCode ¶

func GetRegionCodesForCountryCode(countryCallingCode int) []string

Returns a list with the region codes that match the specific country calling code. For non-geographical country calling codes, the region code 001 is returned. Also, in the case of no region code being found, an empty list is returned.

func GetSupportedCallingCodes ¶

func GetSupportedCallingCodes() map[int]bool

GetSupportedCallingCodes returns all country calling codes the library has metadata for, covering both non-geographical entities (global network calling codes) and those used for geographical entities. This could be used to populate a drop-down box of country calling codes for a phone-number widget, for instance.

func GetSupportedGlobalNetworkCallingCodes ¶

func GetSupportedGlobalNetworkCallingCodes() map[int]bool

GetSupportedGlobalNetworkCallingCodes returns all global network calling codes the library has metadata for.

func GetSupportedRegions ¶

func GetSupportedRegions() map[string]bool

GetSupportedRegions returns all regions the library has metadata for.

func GetSupportedTypesForNonGeoEntity ¶

func GetSupportedTypesForNonGeoEntity(countryCallingCode int) map[PhoneNumberType]bool

GetSupportedTypesForNonGeoEntity returns the types for a country-code belonging to a non-geographical entity which the library has metadata for. Will not include FIXED_LINE_OR_MOBILE or UNKNOWN. No types are returned for country calling codes that do not map to a known non-geographical entity.

func GetSupportedTypesForRegion ¶

func GetSupportedTypesForRegion(regionCode string) map[PhoneNumberType]bool

GetSupportedTypesForRegion returns the types for a given region which the library has metadata for. Will not include FIXED_LINE_OR_MOBILE or UNKNOWN. No types are returned for invalid or unknown region codes.

func IsAlphaNumber ¶

func IsAlphaNumber(number string) bool

Checks if the number is a valid vanity (alpha) number such as 800 MICROSOFT. A valid vanity number will start with at least 3 digits and will have three or more alpha characters. This does not do region-specific checks - to work out if this number is actually valid for a region, it should be parsed and methods such as IsPossibleNumberWithReason() and IsValidNumber() should be used.

func IsCarrierSpecific ¶

func IsCarrierSpecific(number *PhoneNumber) bool

IsCarrierSpecific given a valid short number, determines whether it is carrier-specific (however, nothing is implied about its validity). Carrier-specific numbers may connect to a different end-point, or not connect at all, depending on the user's carrier. If it is important that the number is valid, then its validity must first be checked using IsValidShortNumber or IsValidShortNumberForRegion.

func IsCarrierSpecificForRegion ¶

func IsCarrierSpecificForRegion(number *PhoneNumber, regionDialingFrom string) bool

IsCarrierSpecificForRegion given a valid short number, determines whether it is carrier-specific when dialed from the given region (however, nothing is implied about its validity). Returns false if the number doesn't match the region provided.

func IsEmergencyNumber ¶

func IsEmergencyNumber(number string, regionCode string) bool

Returns true if the given number exactly matches an emergency service number in the given region.

This method takes into account cases where the number might contain formatting, but doesn't allow additional digits to be appended. Note that isEmergencyNumber(number, region) implies connectsToEmergencyNumber(number, region).

number: the phone number to test regionCode: the region where the phone number is being dialed return: whether the number exactly matches an emergency services number in the given region

func IsMobileNumberPortableRegion ¶

func IsMobileNumberPortableRegion(regionCode string) bool

Returns true if the supplied region supports mobile number portability. Returns false for invalid, unknown or regions that don't support mobile number portability.

func IsNANPACountry ¶

func IsNANPACountry(regionCode string) bool

Checks if this is a region under the North American Numbering Plan Administration (NANPA).

func IsNumberGeographical ¶

func IsNumberGeographical(phoneNumber *PhoneNumber) bool

Tests whether a phone number has a geographical association. It checks if the number is associated to a certain region in the country where it belongs to. Note that this doesn't verify if the number is actually in use.

A similar method is implemented as PhoneNumberOfflineGeocoder.canBeGeocoded, which performs a looser check, since it only prevents cases where prefixes overlap for geocodable and non-geocodable numbers. Also, if new phone number types were added, we should check if this other method should be updated too.

func IsNumberGeographicalForType ¶

func IsNumberGeographicalForType(phoneNumberType PhoneNumberType, countryCallingCode int) bool

Overload of IsNumberGeographical(PhoneNumber), since calculating the phone number type is expensive; if we have already done this, we don't want to do it again.

func IsPossibleNumber ¶

func IsPossibleNumber(number *PhoneNumber) bool

Convenience wrapper around IsPossibleNumberWithReason(). Instead of returning the reason for failure, this method returns a boolean value.

func IsPossibleNumberForType ¶

func IsPossibleNumberForType(number *PhoneNumber, numberType PhoneNumberType) bool

IsPossibleNumberForType returns true if the number is a possible number of the given type (a more lenient check than IsValidNumberForRegion).

func IsPossibleNumberFromRegion ¶

func IsPossibleNumberFromRegion(number string, regionDialingFrom string) bool

IsPossibleNumberFromRegion checks whether a phone number is a possible number given a number in the form of a string, and the region where the number could be dialled from. It provides a more lenient check than IsValidNumber. See IsPossibleNumber for details.

This method first parses the number, then invokes IsPossibleNumber with the resultant PhoneNumber object.

regionDialingFrom is the region we expect the number to be dialled from. Note this is different from the region where the number belongs. For example, the number +1 650 253 0000 belongs to the US. When written in this form, it can be dialled from any region. When written as 650 253 0000, it can only be dialled from within the US.

func IsPossibleShortNumber ¶

func IsPossibleShortNumber(number *PhoneNumber) bool

Check whether a short number is a possible number. If a country calling code is shared by multiple regions, this returns true if it's possible in any of them. This provides a more lenient check than #isValidShortNumber. See IsPossibleShortNumberForRegion(PhoneNumber, string) for details.

func IsPossibleShortNumberForRegion ¶

func IsPossibleShortNumberForRegion(number *PhoneNumber, regionDialingFrom string) bool

Check whether a short number is a possible number when dialed from the given region. This provides a more lenient check than IsValidShortNumberForRegion.

func IsSmsServiceForRegion ¶

func IsSmsServiceForRegion(number *PhoneNumber, regionDialingFrom string) bool

IsSmsServiceForRegion given a valid short number, determines whether it is an SMS service (however, nothing is implied about its validity). An SMS service is where the primary or only intended usage is to receive and/or send text messages (SMSs). This includes MMS as MMS numbers downgrade to SMS if the other party isn't MMS-capable. Returns false if the number doesn't match the region provided.

func IsValidNumber ¶

func IsValidNumber(number *PhoneNumber) bool

Tests whether a phone number matches a valid pattern. Note this doesn't verify the number is actually in use, which is impossible to tell by just looking at a number itself.

func IsValidNumberForRegion ¶

func IsValidNumberForRegion(number *PhoneNumber, regionCode string) bool

Tests whether a phone number is valid for a certain region. Note this doesn't verify the number is actually in use, which is impossible to tell by just looking at a number itself. If the country calling code is not the same as the country calling code for the region, this immediately exits with false. After this, the specific number pattern rules for the region are examined. This is useful for determining for example whether a particular number is valid for Canada, rather than just a valid NANPA number. Warning: In most cases, you want to use IsValidNumber() instead. For example, this method will mark numbers from British Crown dependencies such as the Isle of Man as invalid for the region "GB" (United Kingdom), since it has its own region code, "IM", which may be undesirable.

func IsValidShortNumber ¶

func IsValidShortNumber(number *PhoneNumber) bool

Tests whether a short number matches a valid pattern. If a country calling code is shared by multiple regions, this returns true if it's valid in any of them. Note that this doesn't verify the number is actually in use, which is impossible to tell by just looking at the number itself. See IsValidShortNumberForRegion(PhoneNumber, String) for details.

func IsValidShortNumberForRegion ¶

func IsValidShortNumberForRegion(number *PhoneNumber, regionDialingFrom string) bool

Tests whether a short number matches a valid pattern in a region. Note that this doesn't verify the number is actually in use, which is impossible to tell by just looking at the number itself.

func NormalizeDiallableCharsOnly ¶

func NormalizeDiallableCharsOnly(number string) string

Normalizes a string of characters representing a phone number. This strips all characters which are not diallable on a mobile phone keypad (including all non-ASCII digits).

func NormalizeDigitsOnly ¶

func NormalizeDigitsOnly(number string) string

Normalizes a string of characters representing a phone number. This converts wide-ascii and arabic-indic numerals to European numerals, and strips punctuation and alpha characters.

func ParseAndKeepRawInputToNumber ¶

func ParseAndKeepRawInputToNumber(
	numberToParse, defaultRegion string,
	phoneNumber *PhoneNumber) error

Same as ParseAndKeepRawInput(String, String), but accepts a mutable PhoneNumber as a parameter to decrease object creation when invoked many times.

func ParseToNumber ¶

func ParseToNumber(numberToParse, defaultRegion string, phoneNumber *PhoneNumber) error

Same as Parse(string, string), but accepts mutable PhoneNumber as a parameter to decrease object creation when invoked many times.

func TruncateTooLongNumber ¶

func TruncateTooLongNumber(number *PhoneNumber) bool

Attempts to extract a valid number from a phone number that is too long to be valid, and resets the PhoneNumber object passed in to that valid version. If no valid number could be extracted, the PhoneNumber object passed in will not be modified.