dialvalidator: Phone Number Validation Using Google's 'libphonenumber' Metadata

Description

Parses, validates, formats, and classifies phone numbers using Google's 'libphonenumber' metadata. Covers 240+ territories with support for mobile, landline, toll-free, and other number types. Unlike 'dialr', this package requires no Java runtime — metadata is parsed ahead of time from the upstream 'PhoneNumberMetadata.xml' and shipped as a bundled R object. Functions accept character vectors and return simple R types (logical, character, data.frame).

Author(s)

Maintainer: Peeyoosh Chandra pc@strategyandops.co

See Also

Useful links:

• https://pcstrategyandopsco.github.io/dialvalidator/

• https://github.com/pcstrategyandopsco/dialvalidator

• Report bugs at https://github.com/pcstrategyandopsco/dialvalidator/issues

Get the full metadata object

Description

Returns the parsed libphonenumber metadata used internally by all validation functions. Useful for inspection and debugging.

Usage

dv_metadata()

Value

A list with elements cc_to_regions, territories, example_numbers, version, and built.

Examples

meta <- dv_metadata()
meta$version
length(meta$territories)

Get metadata for a specific territory

Description

Get metadata for a specific territory

Usage

dv_territory(region)

Arguments

Value

A list containing the territory's country code, national prefix, phone type patterns, formatting rules, and example numbers. Returns NULL if the region is not found.

Examples

nz <- dv_territory("NZ")
nz$country_code
nz$mobile$example

Update metadata from upstream

Description

Downloads the latest PhoneNumberMetadata.xml from Google's libphonenumber repository, parses it, and saves the result to the user's cache directory. The updated metadata is used for the remainder of the session.

Usage

dv_update_metadata(
  url = paste0("https://raw.githubusercontent.com/google/libphonenumber/master/",
    "resources/PhoneNumberMetadata.xml")
)

Arguments

Details

Requires the xml2 package.

Value

Invisibly returns the path to the cached metadata file.

Examples

dv_update_metadata()

Access Phone Number Metadata

Description

Functions to access and update the bundled libphonenumber metadata.

Detect Country of a Phone Number

Description

Returns the ISO 3166-1 alpha-2 region code for each phone number.

Usage

phone_country(number, default_region = NULL)

Arguments

Value

Character vector of region codes (e.g., "NZ", "US"). Returns NA for numbers that cannot be parsed.

Examples

phone_country("+64211234567")
phone_country(c("+12125551234", "+442071234567"))

Format Phone Numbers

Description

Formats phone numbers according to standard conventions.

Usage

phone_format(
  number,
  format = c("E164", "NATIONAL", "INTERNATIONAL"),
  default_region = NULL
)

Arguments

Value

Character vector of formatted numbers. Returns NA for numbers that cannot be parsed.

Examples

phone_format("+64211234567")
phone_format("+64211234567", "NATIONAL")
phone_format("+64211234567", "INTERNATIONAL")

Get All Phone Number Information

Description

Parses, validates, formats, and classifies phone numbers in a single call. Returns a data frame with one row per input number.

Usage

phone_info(number, default_region = NULL)

Arguments

Value

A data frame with columns:

raw

Original input.

e164

E.164 formatted number.

national

National format.

international

International format.

region

ISO 3166-1 alpha-2 region code.

country_code

Country calling code.

type

Number type (mobile, fixed_line, etc.).

valid

Logical validation result.

Examples

phone_info("+64211234567")
phone_info(c("+64211234567", "+12125551234"))

Parse a Phone Number

Description

Parses a phone number string into its components: country code, national number, and region. Numbers can be provided in international format (with leading +) or national format (with default_region).

Usage

phone_parse(number, default_region = NULL)

Arguments

Value

A list of parsed phone number lists, each with elements:

raw

The original input string.

country_code

Country calling code (e.g., "64" for NZ).

national_number

The national significant number (digits only).

region

ISO 3166-1 alpha-2 region code.

valid

Logical indicating if the number is valid.

Returns a list with valid = FALSE for numbers that cannot be parsed.

Examples

phone_parse("+64211234567")
phone_parse("021 123 4567", default_region = "NZ")
phone_parse(c("+12125551234", "+442071234567"))

Detect Phone Number Type

Description

Classifies phone numbers as mobile, fixed-line, toll-free, etc. by matching against libphonenumber's per-territory type patterns.

Usage

phone_type(number, default_region = NULL)

Arguments

Value

Character vector of phone number types. Possible values: "mobile", "fixed_line", "fixed_line_or_mobile", "toll_free", "premium_rate", "shared_cost", "personal_number", "voip", "pager", "uan", "voicemail", "unknown". Returns NA for numbers that cannot be parsed.

Examples

phone_type("+64211234567")
phone_type(c("+6493001234", "+64800123456"))

Validate Phone Numbers

Description

Checks whether phone numbers are valid according to libphonenumber's metadata. A number is valid if it parses successfully, has a valid length, and matches the general number pattern for its region.

Usage

phone_valid(number, default_region = NULL)

Arguments

Value

Logical vector. TRUE for valid numbers, FALSE otherwise. NA inputs return FALSE.

Examples

phone_valid("+64211234567")
phone_valid(c("+64211234567", "+6421", "not a number"))
phone_valid("021 123 4567", default_region = "NZ")