Phone number validation in Go: parsing, E.164 and rate-limited lookups

go get github.com/nyaruka/phonenumbers/v2@v2.0.12 golang.org/x/time/rate golang.org/x/sync/errgroup

// phone/phone.go
package phone

import (
	"regexp"
	"strings"

	"github.com/nyaruka/phonenumbers/v2"
)

// Our reserved test range (+44 7700 9xxxxx). libphonenumber marks it invalid on purpose.
var testRange = regexp.MustCompile(`^\+4477009\d{5}$`)

type Result struct {
	OK     bool
	E164   string
	Region string
	Type   phonenumbers.PhoneNumberType
	Reason string // unparseable | invalid | too_short | too_long
}

// Normalize parses raw input and returns the E.164 form if the number is valid.
func Normalize(raw, defaultRegion string, allowTestRange bool) Result {
	raw = strings.TrimSpace(raw)
	if raw == "" || len(raw) > 32 {
		return Result{Reason: "unparseable"}
	}
	num, err := phonenumbers.Parse(raw, defaultRegion) // defaultRegion like "GB"; "" requires a leading +
	if err != nil {
		return Result{Reason: "unparseable"}
	}
	e164 := phonenumbers.Format(num, phonenumbers.E164)
	if allowTestRange && testRange.MatchString(e164) {
		return Result{OK: true, E164: e164, Region: "GB"}
	}
	if !phonenumbers.IsValidNumber(num) {
		switch phonenumbers.IsPossibleNumberWithReason(num) {
		case phonenumbers.TOO_SHORT:
			return Result{Reason: "too_short"}
		case phonenumbers.TOO_LONG:
			return Result{Reason: "too_long"}
		}
		return Result{Reason: "invalid"}
	}
	return Result{OK: true, E164: e164, Region: phonenumbers.GetRegionCodeForNumber(num), Type: phonenumbers.GetNumberType(num)}
}

// phone/phone_test.go
package phone

import (
	"testing"

	"github.com/nyaruka/phonenumbers/v2"
)

func TestNormalize(t *testing.T) {
	cases := []struct{ in, region, e164, reason string }{
		{"(202) 555-0143", "US", "+12025550143", ""},
		{"07911 123456", "GB", "+447911123456", ""},
		{"+49 1512 3456789", "", "+4915123456789", ""},
		{"+1 123 456 7890", "", "", "invalid"},     // right length, impossible area code
		{"+44 79111 234567", "", "", "too_long"},
		{"202-555-0143", "", "", "unparseable"},   // no region, no +
		{"07700 900001", "GB", "", "invalid"},     // reserved drama range
	}
	for _, c := range cases {
		r := Normalize(c.in, c.region, false)
		if r.E164 != c.e164 || r.Reason != c.reason {
			t.Errorf("Normalize(%q, %q) = %+v", c.in, c.region, r)
		}
	}
	if r := Normalize("+44 7911 123456", "", false); r.Region != "GG" || r.Type != phonenumbers.MOBILE {
		t.Errorf("got %+v", r)
	}
}

// mv/client.go
package mv

import (
	"bytes"
	"context"
	"encoding/json"
	"fmt"
	"net/http"
	"strconv"
	"time"

	"golang.org/x/time/rate"
)

type Client struct {
	BaseURL string
	APIKey  string
	HTTP    *http.Client
	Limiter *rate.Limiter // client-side pacing: stay under 10 requests/s per key
}

func New(apiKey, baseURL string) *Client {
	if baseURL == "" {
		baseURL = "https://api.mobilevalidate.com"
	}
	return &Client{
		BaseURL: baseURL,
		APIKey:  apiKey,
		HTTP:    &http.Client{Timeout: 45 * time.Second}, // the server may long-poll for up to `wait` seconds
		Limiter: rate.NewLimiter(rate.Limit(8), 8),
	}
}

type CheckResult struct {
	Status     string         `json:"status"`     // completed | unknown | pending | unsupported_country
	Registered *bool          `json:"registered"` // nil = unknown (not false)
	Attributes map[string]any `json:"attributes"`
	Reason     *string        `json:"reason"`
	CheckedAt  *string        `json:"checked_at"`
}

type Result struct {
	Input        string                 `json:"input"`
	E164         *string                `json:"e164"`
	NumberStatus string                 `json:"number_status"` // valid | invalid_number | duplicate | suppressed
	Checks       map[string]CheckResult `json:"checks"`
}

type Lookup struct {
	ID      string   `json:"id"`
	Status  string   `json:"status"` // completed | pending
	Results []Result `json:"results"`
	Next    *struct {
		PollAfterMs int `json:"poll_after_ms"`
	} `json:"next"`
}

type APIError struct {
	Code      string `json:"code"`
	Message   string `json:"message"`
	Status    int    `json:"status"`
	Retryable bool   `json:"retryable"`
}

func (e *APIError) Error() string { return fmt.Sprintf("%s (%d): %s", e.Code, e.Status, e.Message) }

// Lookup checks up to 100 numbers. Numbers go in the POST body, never in the URL.
func (c *Client) Lookup(ctx context.Context, numbers, checks []string) (*Lookup, error) {
	body, _ := json.Marshal(map[string]any{"numbers": numbers, "checks": checks, "wait": 10})
	var l Lookup
	if err := c.do(ctx, http.MethodPost, "/v1/lookup", body, &l); err != nil {
		return nil, err
	}
	for l.Status == "pending" {
		wait := 2 * time.Second
		if l.Next != nil && l.Next.PollAfterMs > 0 {
			wait = time.Duration(l.Next.PollAfterMs) * time.Millisecond
		}
		select {
		case <-ctx.Done():
			return &l, ctx.Err() // partial results; pending checks can be fetched later by id
		case <-time.After(wait):
		}
		if err := c.do(ctx, http.MethodGet, "/v1/lookups/"+l.ID+"?wait=10", nil, &l); err != nil {
			return nil, err
		}
	}
	return &l, nil
}

func (c *Client) do(ctx context.Context, method, path string, body []byte, out any) error {
	for attempt := 0; ; attempt++ {
		if err := c.Limiter.Wait(ctx); err != nil {
			return err
		}
		req, err := http.NewRequestWithContext(ctx, method, c.BaseURL+path, bytes.NewReader(body))
		if err != nil {
			return err
		}
		req.Header.Set("Authorization", "Bearer "+c.APIKey)
		req.Header.Set("Content-Type", "application/json")
		res, err := c.HTTP.Do(req)
		if err != nil {
			return err
		}
		if res.StatusCode < 300 {
			defer res.Body.Close()
			return json.NewDecoder(res.Body).Decode(out)
		}
		var e struct{ Error APIError }
		_ = json.NewDecoder(res.Body).Decode(&e)
		res.Body.Close()
		if !e.Error.Retryable || attempt == 3 {
			return &e.Error
		}
		delay := time.Duration(1<<attempt) * time.Second
		if s, err := strconv.Atoi(res.Header.Get("Retry-After")); err == nil {
			delay = time.Duration(s) * time.Second
		}
		select {
		case <-ctx.Done():
			return ctx.Err()
		case <-time.After(delay):
		}
	}
}

// cmd/demo/main.go (excerpt)
g, ctx := errgroup.WithContext(ctx)
g.SetLimit(4)
var mu sync.Mutex
var results []mv.Result
for start := 0; start < len(numbers); start += 100 {
	batch := numbers[start:min(start+100, len(numbers))]
	g.Go(func() error {
		l, err := client.Lookup(ctx, batch, []string{"carrier"})
		if err != nil {
			return err
		}
		mu.Lock()
		results = append(results, l.Results...)
		mu.Unlock()
		return nil
	})
}
if err := g.Wait(); err != nil {
	var apiErr *mv.APIError
	if errors.As(err, &apiErr) {
		log.Printf("API error: %s", apiErr.Code) // log codes, never phone numbers
	}
	return err
}

skip "+44 1234": invalid
+447700900001 completed mobile
+447700900002 unknown unknown NO_DATA
+447700900003 unknown unknown UPSTREAM_TIMEOUT
+447700900004 completed mobile