phonenumbers

phonenumbers is a Go port of Google’s libphonenumber, tracking the Java reference implementation function-for-function so behavior stays verifiable against upstream. It parses, validates, and formats phone numbers for every country using the same metadata libphonenumber ships, exposing a small top-level API (Parse, IsValidNumber, Format, GetNumberType) built around a single PhoneNumber protobuf message.

Beyond the core package, it ships companion subpackages for carrier name lookup, offline geocoding, and timezone resolution, all built on a shared prefix-mapper abstraction over embedded, gzip-compressed metadata blobs. A documented sync process (SYNC.md, plus a bundled Claude Code skill) keeps the Go code reconciled against new upstream libphonenumber releases, separating mechanical metadata regeneration from the judgment work of porting logic changes.

What You Get

• Parsing and validation of phone numbers for every country/region libphonenumber supports, via Parse and IsValidNumber
• Formatting into E164, national, international, and RFC3966 formats through a single Format function
• As-you-type formatting for live input fields, mirroring libphonenumber’s AsYouTypeFormatter
• Companion carrier, geocoding, and timezone subpackages for carrier name, geographic description, and timezone lookups on a validated number
• Short-number detection (emergency numbers, SMS short codes) via a dedicated shortnumberinfo module
• A cmd/buildmetadata tool to regenerate embedded metadata from any upstream libphonenumber release

Common Use Cases

• Validating and normalizing user-submitted phone numbers on signup or checkout forms
• Formatting stored phone numbers consistently for display (national) versus storage/dialing (E164)
• Detecting the number type (mobile, fixed line, toll-free, premium rate) to route SMS/voice traffic correctly
• Enriching a phone number with carrier or geographic metadata for fraud checks or analytics
• Live-formatting phone number input as a user types it into a form field

Under The Hood

Architecture The library is organized as a strict, file-by-file port of Google’s Java libphonenumber, with core parsing/formatting/validation logic concentrated in phonenumberutil.go and matching logic in phonenumbermatcher.go, alongside separate embedded-metadata-backed subpackages (carrier, geocoding, timezone) that share a common internal/prefixmapper abstraction for prefix-based lookups against gzipped metadata blobs. Narrow internal packages (character, regexcache, serialize, stringbuilder, regexbasedmatcher, metadatabuilder) provide single-purpose helpers reused across the main package and subpackages. Comments cross-reference the exact upstream Java source file each Go file ports, keeping the architecture’s shape deliberately mirrored rather than independently designed — good for auditability against upstream, though it favors upstream fidelity over idiomatic Go restructuring.

Tech Stack Built as a Go 1.25 module with a minimal external dependency footprint: golang.org/x/text for language display names in geocoding, google.golang.org/protobuf for the PhoneNumber message type generated from phonenumber.proto/phonemetadata.proto, and stretchr/testify for test assertions only. Metadata ships as gzip-compressed XML blobs embedded via go:embed and decoded through a custom internal serialization stack, regenerated from upstream libphonenumber releases via a dedicated cmd/buildmetadata tool; a cmd/phoneparser CLI serves as a minimal usage demo. CI runs the test suite across a matrix of upcoming Go versions on every push and pull request.

Code Quality Test coverage is extensive — the core package’s test file alone is around 140KB, with additional dedicated suites for the as-you-type formatter, matcher, short-number info, metadata source, example numbers, and each subpackage, all using testify assertions, plus a synthetic test-metadata fixture for isolated testing. Errors are typed and explicit rather than swallowed: errors.go defines sentinel errors (ErrTooShortAfterIDD, ErrNumTooLong) and aliases a metadata-package error, and the ported NumberParseException becomes a proper Go error type. No separate linter config is visible beyond go test in CI, but naming and structure consistently mirror upstream Java for traceability.

API Design The public API centers on a handful of top-level functions (Parse, IsValidNumber, Format, GetNumberType) operating on a single PhoneNumber protobuf struct, keeping the primary import surface approachable despite a large implementation underneath. Subpackages extend that same PhoneNumber type with additive lookups (carrier, geocoding, timezone) rather than parallel data structures, keeping composition simple for callers. The design isn’t inventing new phone-parsing techniques — it deliberately mirrors Google’s own libphonenumber logic and Java-derived naming conventions, trading some Go idiom for close upstream traceability through a documented reconciliation process.