libphonenumber

The metadata directory provides auxiliary libraries designed to read and manipulate the CSV-packaged metadata used by the libphonenumber client libraries.

Currently, these tools focus on processing CSV files. The long-term goal is for these tools to manage the CSV files as the single source of truth, from which XML-based metadata and other mapping files will be automatically generated.

libphonenumber is a library for parsing, formatting, and validating international phone numbers. Key capabilities include:

• Parsing & Validation: isValidNumber (full validation) and isPossibleNumber (fast length-based check).
• Formatting: Support for various formats including E164, INTERNATIONAL, and NATIONAL.
• Type Detection: getNumberType distinguishes between Fixed-line, Mobile, Toll-free, VoIP, etc.
• Metadata Services: Geocoding (PhoneNumberOfflineGeocoder), Carrier mapping (PhoneNumberToCarrierMapper), and Timezone mapping (PhoneNumberToTimeZonesMapper).
• Text Processing: findNumbers to extract numbers from text and isNumberMatch to check if two numbers refer to the same entity.

The E.164 Formatter is an Android application designed to demonstrate how to use the libphonenumber (LPN) library in a real-world Java-based Android environment. It specifically demonstrates reading device contacts and reformatting local phone numbers into the E.164 standard.

Key functionalities demonstrated include:

• Parsing local phone numbers based on a user-selected country.
• Identifying valid, parsable numbers that can be converted to E.164.
• Categorizing numbers that cannot be formatted (e.g., due to parsing errors, being too short, being invalid, or already being in E.164 format).
• Batch updating contact entries with reformatted E.164 numbers.

libphonenumber does not support M2M numbers in general. The library is designed for numbers that a human might call or send an SMS to, assuming standard costs and reachability.

Exception: The library supports the Netherlands 097X M2M range because official authorities state they should be treated like regular mobile numbers. However, users should be aware of potential false positives where a number is categorized as MOBILE but is actually used for pure M2M purposes.

In the context of this library, metadata refers to the comprehensive information required to handle phone numbering for a specific country. This includes:

• Country calling codes.
• International and national dialing prefixes.
• Operational carrier codes.
• Valid and possible number ranges for a country.
• Optimal formatting rules.
• Geographical area prefixes.

Phone number formatting in libphonenumber is country-specific and language-independent.

• Do not attempt to format a number using the conventions of a different country (e.g., formatting a US number using French formatting rules) even if the user is French. This is considered undefined and incorrect behavior.
• The library currently supports parsing native (non-ASCII) digits, but it does not support using them during formatting at this time.

The metadata.zip file contains the canonical metadata for the libphonenumber project. This file is intended for use by libphonenumber tools.

Warning: CSV schemas within this package are not guaranteed to be stable.

The library only supports a country if it meets specific criteria. A country may be unsupported if:

• It does not have a single country calling code: If a country uses multiple codes (e.g., Kosovo using codes from Serbia, Monaco, or Slovenia), numbers are mapped to those respective countries.
• The country no longer exists: Dissolved political entities (e.g., Yugoslavia, Netherlands Antilles) are not supported.
• There is no usable numbering plan: Small populations using satellite phones without a dedicated national plan (e.g., Pitcairn Island) are not supported.
• No assigned region code: The country must have an assigned region code (e.g., via CLDR).

The parse() method attempts to extract a phone number from a string and may convert alpha characters to digits if the input resembles a 'vanity number'.

• Vanity Numbers: Characters are converted to digits (e.g., +1 412 535 abcd becomes +1 412 535 2223).
• Mistyped Extra Characters: If an extra alpha character is inserted in the middle, the library ignores it (e.g., +1 412 535 c0000 becomes +1 412 535 0000).
• Mistyped Replacement Characters: If an alpha character replaces a digit and the resulting sequence is not a valid number, the character is not converted and the number is marked invalid (e.g., +1 412 535 c000 is invalid).

While the library usually removes a country's national or trunk prefix (like a leading zero) to normalize the number, it will retain the prefix in these cases:

1. No National Prefix: If the country does not use a national prefix, the leading zero is kept so it can be re-added during formatting.
2. International Dialing Requirements: If a leading zero is required for dialing from abroad (e.g., Italy), it is stored as part of the national number.
3. Short/Emergency Numbers: If the number is too short to be a standard valid number (e.g., the Australian emergency number 000), the prefix is not removed to prevent losing the necessary formatting for that specific short-code.