postcode

Nigerian Postcode Go SDK (postcode)

A high-performance, zero-allocation Go client library for Nigeria's National Digital Alphanumeric Postcode system (docs.postcode.gov.ng).

Features

• Zero-Allocation Parsing: postcode.Parse() parses and validates 11-character postcodes with 0 heap escapes (~28ns/op).
• Safe & Idiomatic Go: Fully memory-safe accessors, Go range-over-func iterators (postcode.ParseSeq), standard errors (errors.As), and functional options.
• Protocol Conformance: Built to match the official NIPOST OpenAPI spec (GET /v1/lookup, GET /v1/search/autocomplete, GET /v1/search/nearby, GET /v1/search/reverse, and POST /v1/assembly/assemble).
• Resilient Transport: Production-tuned HTTP transport with exponential backoff, full jitter, Retry-After header support, and safe connection draining.
• Pluggable Observability: Zero external dependencies in the core module, with an optional OpenTelemetry module (github.com/abcubed3/postcode/otelpostcode).

Installation

Requires Go 1.27+:

go get github.com/abcubed3/postcode

Quickstart

package main

import (
	"context"
	"errors"
	"fmt"
	"log"
	"time"

	"github.com/abcubed3/postcode"
)

func main() {
	ctx := context.Background()

	// 1. High-throughput client with functional options
	client, err := postcode.NewClient()
	if err != nil {
		log.Fatal(err)
	}

	// 2. Graded postcode lookup (Level 1 is free, Level 2-3 require commercial credits)
	res, err := client.Lookup(ctx, "EK 01 A03 FK 01", postcode.Level1)
	if err != nil {
		var apiErr *postcode.APIError
		if errors.As(err, &apiErr) && apiErr.IsInsufficientCredits() {
			log.Fatalf("Top up required: %v", apiErr)
		}
		log.Fatalf("Lookup failed: %v", err)
	}
	fmt.Printf("Postcode: %s, Valid: %t\n", res.Postcode, res.Valid)

	// 3. Segment-aware autocomplete
	suggs, err := client.Autocomplete(ctx, "EK 01 A")
	if err != nil {
		log.Fatalf("Autocomplete failed: %v", err)
	}
	fmt.Printf("Active segment: %s, Suggestions: %+v\n", suggs.Segment, suggs.Suggestions)

	// 4. Batch streaming parse 
	records := []string{"EK 01 A03 FK 01", "INVALID_CODE", "FC 02 A09 DB 09"}
	for p, err := range postcode.ParseSeq(records) {
		if err != nil {
			fmt.Printf("Skipping invalid entry: %v\n", err)
			continue
		}
		fmt.Printf("Parsed: %s (State: %s, LGA: %s, Unit: %s)\n",
			p.Formatted(), p.State(), p.LGA(), p.BuildingUnit())
	}
}

API Surface

Live Server Simulator

For local development and automated CI testing without incurring API fees or requiring live network access, the SDK includes an in-memory mock server pre-loaded with all official test postcodes from docs.postcode.gov.ng:

1. Run as a Standalone Server

# Start on localhost:8080 (or specify -port 8080)
go run ./cmd/simulator

Test with curl:

# L1 Public validity lookup (Free, no auth)
curl "http://localhost:8080/v1/lookup?code=EK-01-A03-FK-01&level=1"

# L3 Commercial lookup (Requires X-API-Key header)
curl "http://localhost:8080/v1/lookup?code=EK-01-A03-FK-01&level=3" \
  -H "X-API-Key: nipost_live_test"

2. Embed Directly in Go Unit & Integration Tests

import "github.com/abcubed3/postcode/simulator"

func TestMyService(t *testing.T) {
    srv := simulator.NewServer() // Starts httptest.Server
    defer srv.Close()

    client, err := postcode.NewClient(
        postcode.WithBaseURL(srv.URL),
        postcode.WithAPIKey("test_key"),
    )
    // Run your application tests against srv.URL
}

3. Preloaded Test Postcodes

Rate Limiting & Resilient Retries

As specified in the NIPOST Authentication Documentation, all authenticated gateway requests are rate-limited per key. The gateway returns quota headers on every response:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 597

When quota is exceeded, the gateway returns 429 Too Many Requests with a cooldown duration.

Intelligent 429 Handling

• Automatic Cooldown Synchronization: On receiving HTTP 429, the transport extracts cooldown intervals from Retry-After (integer seconds or RFC1123 HTTP dates) and X-RateLimit-Reset, adding randomized jitter to avoid thundering herds when the window resets.
• Fail-Fast Defense (MaxRateLimitDelay): If the gateway requests a cooldown longer than the configured threshold (default: 10s), the client aborts immediately, preventing goroutine hangs and wasted retries.
• Live Quota Introspection: Call client.RateLimit() at any time to inspect Remaining, Limit, and ResetAt in a thread-safe manner without making extra network calls.
• Rich Error Context: apiErr.IsRateLimit() returns true on 429 errors, exposing apiErr.RetryAfter and apiErr.RateLimit.

// 1. Fine-tune rate limit retries
client, err := postcode.NewClient(
    postcode.WithAPIKey("nipost_live_..."),
    postcode.WithRateLimitRetry(true, 5*time.Second), // Max wait threshold: 5s
)

// 2. Inspect rate limit quota
if rl := client.RateLimit(); rl != nil {
    fmt.Printf("Quota remaining: %d/%d (resets at %v)\n", rl.Remaining, rl.Limit, rl.ResetAt)
}

// 3. Structured error handling
res, err := client.Lookup(ctx, "EK-01-A03-FK-01", postcode.Level2)
if err != nil {
    var apiErr *postcode.APIError
    if errors.As(err, &apiErr) && apiErr.IsRateLimit() {
        log.Printf("Rate limit exceeded. Try again in %v", apiErr.RetryAfter)
    }
}

OpenTelemetry Integration

Install the telemetry adapter submodule:

go get github.com/abcubed3/postcode/otelpostcode

Hook it into your client:

package main

import (
	"context"
	"log"

	"github.com/abcubed3/postcode"
	"github.com/abcubed3/postcode/otelpostcode"
)

func main() {
	// Initialize tracing and metrics from global OTel providers
	tel, err := otelpostcode.NewTelemetry()
	if err != nil {
		log.Fatal(err)
	}

	client, err := postcode.NewClient(
		postcode.WithAPIKey("YOUR_API_KEY"),
		postcode.WithTelemetry(tel),
	)
	if err != nil {
		log.Fatal(err)
	}

	_, _ = client.Lookup(context.Background(), "EK 01 A03 FK 01", postcode.Level2)
}

Benchmarks

Microbenchmarks measured on darwin/arm64 (Apple M2 Max) using go test -bench=. -benchmem:

BenchmarkParse-12          38183524        28.20 ns/op          0 B/op        0 allocs/op
BenchmarkFormatted-12     195602528         6.15 ns/op          0 B/op        0 allocs/op

• postcode.Parse: Fully validates, normalizes, and extracts segments with 0 B/op and 0 allocs/op in ~28 ns/op.
• postcode.Formatted: Formats canonical hyphenated postcodes (AA-99-H77-BB-55) with 0 B/op and 0 allocs/op in ~6 ns/op.