We've released phonenumber, a Go port of Google's libphonenumber for parsing, validating and formatting international phone numbers — with no dependencies outside the standard library.

Phone numbers look like the simplest field on a form. They aren't. The same number can arrive as 020 7946 0958, +44 (0)20-7946-0958 or tel:+44-20-7946-0958, and whether it is a real number at all depends on a numbering plan that differs in every country and changes every few weeks.

Get it wrong and the cost turns up somewhere else: a verification text that never arrives, a customer who exists twice in your CRM because they typed their number two different ways, a support team that can't call anyone back. Google's libphonenumber is the reference for getting this right. phonenumber brings it to Go.

n, err := phonenumber.Parse("020 7946 0958", "GB")
if err != nil {
	return err
}
n.Valid()                           // true
n.Type()                            // phonenumber.FixedLine
n.Format(phonenumber.International) // "+44 20 7946 0958"
n.FormatFrom("US")                  // "011 44 20 7946 0958"

What You Get

Every public class of upstream's Java library has a Go counterpart: parsing, validation and number types, formatting, comparing numbers, finding numbers in text, formatting as you type, short and emergency numbers, and geocoding, carrier and time zone lookups. The API follows Go conventions rather than Java's.

• A value type. Number is a small comparable struct. Compare numbers with ==, use them as map keys, copy them freely.
• Fits the standard library. Number encodes as E.164 and works as a field with encoding/json and in database/sql rows. The zero value is stored as NULL.
• Safe to log. Errors never include the number itself.
• Pay for what you use. Each region's patterns are compiled the first time a number from that region is seen, and the geocoding, carrier and time zone data only reach your binary if you import those packages.
• No dependencies. The metadata is generated into Go source. No protobuf, no runtime XML parsing.

Kept Current

A port of libphonenumber is only as good as its metadata, and the metadata goes stale fast. Upstream's own test suite is ported and runs against upstream's test metadata, so behaviour matches the reference. A daily workflow checks for new upstream releases, regenerates the metadata, runs the tests and tags a patch release. Keeping up to date is a go get -u, not a project.

Get It

go get uradical.io/go/phonenumber

phonenumber requires Go 1.27 or later and is Apache 2.0-licensed, the same as upstream. It's an independent port and isn't affiliated with Google. There's an overview on the phonenumber page, and the code and full documentation are at github.com/uRadical/phonenumber.