gophonenumber

README

gophonenumber

Go package gophonenumber provides phone numbers categorization and normalization logic.

Documentation

Index

• Constants
• Variables
• func IsPhoneNumber(ctx context.Context, fl validator.FieldLevel) bool
• func IsValidLanguageCode(regionCode string) bool
• type ExtensionNumber
  • func ParseExtensionNumber(number string, maxLength int) (ExtensionNumber, error)
• type IsPhoneNumberContextData
• type NormalisedNumberData
  • func QueryExtensionNumber(number string, maxExtensionLength int) (NormalisedNumberData, error)
  • func QueryExternalPhoneNumber(number, country, language string) (NormalisedNumberData, error)
  • func QueryNumber(number, country, language string, acceptExtension bool, maxExtensionLength int) (NormalisedNumberData, error)
  • func (d NormalisedNumberData) String() string
• type NumberCategory
• type NumberRange
  • func GetCategoryForNumber(number, country string) (numberRange NumberRange, found bool)
  • func MustGetPhoneNumberRangeByPattern(country, pattern string) *NumberRange
• type NumberType
  • func (t NumberType) MarshalJSON() ([]byte, error)
  • func (t NumberType) String() string
• type PhoneNumberContextKey
  • func (c PhoneNumberContextKey) GetContextKey() string
• type PhoneNumberRanges
  • func GetNumberRanges() PhoneNumberRanges
  • func QueryPhoneNumberRanges() PhoneNumberRanges

Constants

const (
	IsPhoneNumberContextKey = PhoneNumberContextKey("is_phone_number_validator_ctx")
)

Variables

var (
	ErrInvalidCountry        = phonenumbers.ErrInvalidCountryCode
	ErrInvalidLanguage       = errors.New("invalid language code")
	ErrNumberTooLong         = phonenumbers.ErrNumTooLong
	ErrNumberTooShort        = phonenumbers.ErrTooShortNSN
	ErrNumberNotAPhoneNumber = phonenumbers.ErrNotANumber
	ErrNumberNotAnExtension  = errors.New("number not an extension")
)

Errors that may result from QueryPhoneNumber.

var (
	ErrNumberNotANumber = errors.New("not a number")
)

Functions

func IsPhoneNumber

func IsPhoneNumber(ctx context.Context, fl validator.FieldLevel) bool

IsPhoneNumber validates whether the field contains a valid phone number based on client country/language.

func IsValidLanguageCode

func IsValidLanguageCode(regionCode string) bool

Types

type ExtensionNumber

type ExtensionNumber string

func ParseExtensionNumber

func ParseExtensionNumber(number string, maxLength int) (ExtensionNumber, error)

ParseExtensionNumber returns the given number as ExtensionNumber when it is valid. Returning an error when the number is not a valid extension.

type IsPhoneNumberContextData

type IsPhoneNumberContextData struct {
	CountryCode string
	Language    string
}

type NormalisedNumberData

type NormalisedNumberData struct {
	IsValid    bool `json:"is_valid"`
	IsPossible bool `json:"is_possible"`

	NumberType         NumberType `json:"number_type"`
	CountryCallingCode int32      `json:"country_calling_code"`
	Country            string     `json:"country"`
	Location           string     `json:"location"`
	TimeZones          []string   `json:"timezones"`

	DialNumber             string `json:"dial_number"`
	InternationalFormatted string `json:"international_formatted"`
	NationalFormatted      string `json:"national_formatted"`

	NumberCategory *NumberRange `json:"number_category,omitempty"`
}

NormalisedNumberData contains information on a phone number or extension.

func QueryExtensionNumber

func QueryExtensionNumber(number string, maxExtensionLength int) (NormalisedNumberData, error)

QueryExtensionNumber checks if the given number CAN be a valid extension for our platform. Returns a populated NormalisedNumberData if it is.

May return errors ErrNumberNotANumber or ErrNotAnExtension.

func QueryExternalPhoneNumber

func QueryExternalPhoneNumber(number, country, language string) (NormalisedNumberData, error)

QueryExternalPhoneNumber fills in a NormalisedNumberData for the given telephone number and country. Country is optional, a two character region code of the originating country. This is for cases where the number doesn't contain a country code prefix or when the caller is from a different country than the number that's being called. Language can optionally be specified as BCP-47, to translate the guessed Location of the number to the language.

May return sentinel errors defined in this package, including: ErrInvalidCountry when an invalid country code is given and ErrInvalidLanguage when an invalid BCP-47 language is given.

func QueryNumber

func QueryNumber(number, country, language string, acceptExtension bool, maxExtensionLength int) (NormalisedNumberData, error)

QueryNumber wraps QueryExternalPhoneNumber, calling QueryExtension when external returned NormalisedNumberData.IsValid=false.

func (NormalisedNumberData) String

func (d NormalisedNumberData) String() string

type NumberCategory

type NumberCategory string

var (
	CategoryInfoPaid      NumberCategory = "info-paid"
	CategoryNatMobile     NumberCategory = "nat-mobile"
	CategoryNatLand       NumberCategory = "nat-land"
	CategoryAmusement     NumberCategory = "amusement"
	CategoryErotica       NumberCategory = "erotica"
	CategoryInfoFree      NumberCategory = "info-free"
	CategoryInternational NumberCategory = "international"
	CategoryAssist        NumberCategory = "assist"
	CategoryComm          NumberCategory = "comm"
	CategoryUnknown       NumberCategory = "unknown"
)

type NumberRange

type NumberRange struct {
	AsteriskPattern string `json:"asterisk_pattern"`
	RegexPattern    string `json:"regex_pattern"`

	Category NumberCategory `json:"category"`
	// contains filtered or unexported fields
}

NumberRange is a numbercategory, with a pattern matchers to match numbers which are that category. Pattern matches exist for both Aterisk format and regular expressions format.

func GetCategoryForNumber

func GetCategoryForNumber(number, country string) (numberRange NumberRange, found bool)

GetCategoryForNumber searches for a NumberRange which matches the given phone number, for the given country.

func MustGetPhoneNumberRangeByPattern

func MustGetPhoneNumberRangeByPattern(country, pattern string) *NumberRange

MustGetPhoneNumberRangeByPattern searches for a NumberRange with the exact asterisk pattern. Panics if the NumberRange does not exist.

type NumberType

type NumberType string

const (
	NumberTypeUnknown   NumberType = "unknown"
	NumberTypeFixed     NumberType = "fixed"
	NumberTypeMobile    NumberType = "mobile"
	NumberTypeExtension NumberType = "extension"
)

func (NumberType) MarshalJSON

func (t NumberType) MarshalJSON() ([]byte, error)

func (NumberType) String

func (t NumberType) String() string

type PhoneNumberContextKey

type PhoneNumberContextKey string

PhoneNumberContextKey is used to define keys for storing/fetching values from a context in gophonenumber.

func (PhoneNumberContextKey) GetContextKey

func (c PhoneNumberContextKey) GetContextKey() string

type PhoneNumberRanges

type PhoneNumberRanges map[string][]NumberRange

func GetNumberRanges

func GetNumberRanges() PhoneNumberRanges

func QueryPhoneNumberRanges

func QueryPhoneNumberRanges() PhoneNumberRanges

QueryPhoneNumberRanges returns a phone number categories and ways to patern match them.