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).
• AI & Agent Native: Built-in Model Context Protocol (MCP) server (postcode mcp), standard LLM function calling schemas (Gemini, OpenAI, Anthropic), and actionable diagnostic self-correction (postcode.Diagnose).
• Shareable & Printable QR Codes: Built-in, dependency-free ISO/IEC 18004 QR encoder (postcode.GenerateQR) rendering SVG, PNG, Base64 Data URIs, terminal Unicode, and print-ready NIPOST postcode labels.
• Web Client Component: Embeddable <nipost-address-input> custom element (@abcubed3/nipost-address-input) with smart freeform address parsing, 774 LGA centroids, self-healing diagnostics, and form participation powered by @abcubed3/postcode-wasm.

Installation

Requires Go 1.27+ (for Go SDK).

Go Library (SDK)

Add the core library to your Go project:

go get github.com/abcubed3/postcode

Command-Line Interface (postcode)

Install the postcode CLI binary directly to your $GOPATH/bin:

go install github.com/abcubed3/postcode/cmd/postcode@latest

Or download pre-compiled binaries for Linux, macOS, and Windows from GitHub Releases.

Verify installation:

postcode version

Web Client Component (@abcubed3/nipost-address-input)

Install the embeddable Web Component via npm:

npm install @abcubed3/nipost-address-input

Or load directly from a CDN without an installation step:

<script type="module" src="https://unpkg.com/@abcubed3/nipost-address-input"></script>

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. Generate Google Maps URL & Coordinates from 11-digit postcode string
    gmapsURL, err := postcode.GoogleMapsURL("EK-01-A03-FK-01")
    if err != nil {
        log.Fatalf("Mapping failed: %v", err)
    }
    lat, lng, _ := postcode.Coordinates("EK-01-A03-FK-01")
    fmt.Printf("Google Maps URL: %s\n", gmapsURL)
    fmt.Printf("Coordinates: %.6f, %.6f\n", lat, lng)

    // 5. 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())
    }

    // 6. Generate shareable & printable QR code (pure Go, zero CGO/dependencies)
    qr, err := postcode.GenerateQR("EK-01-A03-FK-01", postcode.QROptions{
        Payload: postcode.QRPayloadPostcode,
        Level:   postcode.QRLevelM,
    })
    if err == nil {
        _ = qr.SaveSVG("ekiti-postcode.svg")
        fmt.Println(qr.Terminal())
    }
}

API Surface

Shareable & Printable QR Codes

Every validated Nigerian digital postcode can be converted into a high-density, printable, or shareable ISO/IEC 18004 QR code with zero external Go dependencies and zero CGO.

1. Multi-Format Rendering & File Helpers

qr, err := postcode.GenerateQR("LA-11-W06-TC-10", postcode.QROptions{
    Payload:         postcode.QRPayloadGoogleMaps, // Encodes direct navigation link
    Size:            300,                          // Pixel/SVG dimension
    ForegroundColor: "#0B6623",                    // NIPOST Nigerian Postal Green
    BackgroundColor: "#FFFFFF",
})
if err != nil {
    log.Fatal(err)
}

// In-memory renderers
svgData     := qr.SVG()                                  // Scalable Vector Graphics string
pngBytes, _ := qr.PNG()                                  // Compressed PNG image bytes
htmlPage    := qr.PrintableHTML()                        // Self-contained, print-styled HTML badge
termView    := qr.Terminal()                             // Unicode half-block characters for stdout
dataURI, _  := qr.DataURI()                              // data:image/png;base64,...

// Direct file export helpers
_ = qr.SaveSVG("lagos-postcode.svg")
_ = qr.SavePNG("lagos-postcode.png")
_ = qr.SaveHTML("lagos-label.html")

2. Print-Ready NIPOST Delivery Badges & Labels

Generate professional delivery labels with the official NIPOST green badge header, human-readable postcode segments, and physical locality description for package shipping and building signage:

qr, _ := postcode.GenerateQR("EK-01-A03-FK-01", postcode.QROptions{
    IncludeLabel: true,
    Title:        "NIPOST DIGITAL POSTCODE",
    Subtitle:     "NTA Road, Back of Fabian Hotel, Ado Ekiti",
})

// Generates an SVG shipping label with clear typography and quiet zones
labelSVG := qr.LabelSVG()
_ = qr.SaveSVG("ekiti-delivery-badge.svg")

3. Payload Options

4. CLI QR Generation

# Print QR code directly in the terminal
postcode qr EK-01-A03-FK-01

# Save SVG and PNG
postcode qr LA-11-W06-TC-10 --render svg --out ikeja.svg
postcode qr LA-11-W06-TC-10 --render png --out ikeja.png

# Generate a printable shipping label badge and preview in browser
postcode qr EK-01-A03-FK-01 --label --out label.svg --open

# Encode direct turn-by-turn navigation for delivery couriers
postcode qr FC-03-B06-AG-12 --payload directions --out abuja-nav.svg

Web Client Component (<nipost-address-input>)

For web applications, checkout flows, and logistics portals, the repository provides an official embeddable Web Component (packages/address-input) published on npm as @abcubed3/nipost-address-input:

• Framework-Agnostic Web Component: Runs natively in plain HTML, React, Next.js, Vue, Angular, Svelte, or server-rendered templates (Django, Laravel, Go html/template).
• Hybrid Dual-Mode UX:
  • Smart Quick-Paste / Search: Users can paste freeform address strings (e.g. "Plot 14 Admiralty Way, Lekki Phase 1, Opposite Domino's Pizza, Lagos"). The disambiguation engine isolates the State, LGA, Locality, Landmark, Street, and canonical 11-character NIPOST Postcode.
  • Expandable Structured Breakdown: Toggle to cascading dropdowns for 37 States + FCT and all 774 Nigerian LGAs.
• Form-Associated Custom Element: Automatically registers with native HTML <form> submissions, submitting structured sub-keys (shipping_address[state], shipping_address[lga], shipping_address[postcode], shipping_address[latitude], etc.) with zero custom JavaScript serializers.
• Self-Healing Diagnostics: Visual 5-segment chips (SS-LL-DDD-AA-UU) with instant tips for legacy 6-digit codes or illegal units (00).
• Edge WASM Speed: Zero external network requests needed for validation or LGA extraction — powered entirely by @abcubed3/postcode-wasm.
• Theming & Design Tokens: Preset themes (light, dark, minimal, unstyled), CSS custom properties (--nipost-primary, etc.), and Shadow DOM ::part() styling.

HTML Form Integration

<!-- 1. Drop script in <head> or before </body> -->
<script type="module" src="https://unpkg.com/@abcubed3/nipost-address-input"></script>

<!-- 2. Embed inside any standard HTML form -->
<form action="/checkout" method="POST">
  <nipost-address-input
    name="shipping_address"
    placeholder="Enter street, landmark, or 11-digit NIPOST code..."
    theme="light"
    required
  ></nipost-address-input>

  <button type="submit">Place Order</button>
</form>

<script>
  const widget = document.querySelector('nipost-address-input');

  // Keystroke-level draft updates
  widget.addEventListener('nipost-change', (e) => {
    console.log('Address draft:', e.detail.address);
  });

  // Canonical NIPOST postcode verified
  widget.addEventListener('nipost-resolve', (e) => {
    console.log('Verified Postcode:', e.detail.postcode);
    console.log('Centroid Coords:', e.detail.address.latitude, e.detail.address.longitude);
  });
</script>

💻 Runnable Example: Check out examples/address_input_web/ for a ready-to-run interactive checkout demo with live telemetry and FormData inspection.

Command-Line Interface (postcode)

The repository includes a production-grade CLI binary for terminal and pipeline workflows:

# Install the CLI
go install github.com/abcubed3/postcode/cmd/postcode@latest

Key CLI Capabilities

• Offline Validation: postcode validate "EK 01 A03 FK 01" (grammar, format, state codes, exit codes).
• Diagnostic Self-Correction: postcode diagnose "ZZ 00 A03 FK 00" (segment errors, state typo suggestions, agent tips).
• Segment Parsing: postcode parse "LA 11 W06 TC 10" -o json (extracts State, LGA, District, Area, Unit, Zone).
• Format Normalization: cat dirty.txt | postcode format --style canonical (Unix pipe friendly).
• Geocoding & Maps: postcode map EK-01-A03-FK-01 (generates Google Maps, Apple Maps, OSM URLs).
• Shareable & Printable QR Codes: postcode qr EK-01-A03-FK-01 --label --out label.svg (renders terminal Unicode, SVG, PNG, Data URI, or printable NIPOST badges).
• Batch CSV Processing: postcode batch --input orders.csv --output enriched.csv --column postcode (processes >350k rows/sec offline).
• Gateway Operations: postcode lookup, postcode autocomplete, postcode nearby, postcode reverse, and postcode status.
• Model Context Protocol: postcode mcp (exposes stdio MCP server for Claude Desktop, Cursor, Antigravity IDE).
• Embedded Simulator: postcode serve --port 2340 (runs local mock NIPOST gateway directly, with optional --data flag).

📖 Full User Guide: For complete documentation, command options, and real-world recipes, see the CLI User Guide & Reference.

Live Server Simulator

For local development and automated CI testing without incurring API fees or requiring live network access, the toolkit 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 the simulator directly via the CLI:

# Start on localhost:2340 (or specify --port 2340)
postcode serve --port 2340

# Or run directly from source without installation:
go run ./cmd/postcode serve --port 2340

Test with curl:

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

# L3 Commercial lookup (Requires X-API-Key header)
curl "http://localhost:2340/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)
}

AI Agents & Model Context Protocol (MCP)

The postcode toolkit is engineered as a first-class geocoding foundation for AI models and autonomous agents.

1. Model Context Protocol (MCP) Server

Connect the toolkit directly to Claude Desktop, Cursor, Antigravity IDE, or custom agent runners using the standard MCP protocol:

# Start MCP server via CLI
postcode mcp

Claude Desktop Configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "postcode": {
      "command": "postcode",
      "args": ["mcp"],
      "env": {
        "POSTCODE_API_KEY": "YOUR_NIPOST_API_KEY"
      }
    }
  }
}

2. Native LLM Function Calling (postcode.DefaultAgentTools)

Export standard JSON-Schema Draft-07 tool declarations compatible with Google Gemini, OpenAI, and Anthropic (covering validation, diagnostics, coordinates, reverse geocoding, nearby radius search, autocomplete, graded lookups, states and LGA reference catalogs, and segment-level assembly and disassembly):

// 1. Get standard tool definitions
tools := postcode.DefaultAgentTools()
for _, t := range tools {
    geminiDecl := t.GeminiFunctionDeclaration() // Google Gemini
    openAIFunc := t.OpenAITool()                 // OpenAI / Mistral / Ollama
    anthropicTool := t.AnthropicTool()           // Anthropic Claude
}

// 2. Dispatch tool calls seamlessly
dispatcher := postcode.NewAgentDispatcher(client)
jsonResult, err := dispatcher.DispatchString(ctx, toolName, argsJSON)

3. Diagnostic Self-Correction (postcode.Diagnose)

Traditional validators return opaque errors that cause agents to hallucinate. postcode.Diagnose() generates structured, actionable guidance with typo suggestions that agents can use to self-correct in subsequent reasoning steps:

report := postcode.Diagnose("ZZ 00 A03 FK 00")
// report.Diagnoses -> Segment-by-segment errors with closest valid state suggestions
// report.ActionableTip -> "Fix State: consider ZA (Zamfara); Fix LGA: 00 invalid (01-99)..."
// report.FormatScore -> 40.0 / 100.0

4. Autonomous Agent Budget & Quota Guardrails

Autonomous agents in reasoning loops can quickly burn API credits or encounter rate limits. Configure safety ceilings and automated fallback behaviors:

client, err := postcode.NewClient(
    postcode.WithAPIKey("YOUR_KEY"),
    postcode.WithAgentGuard(postcode.AgentGuardConfig{
        MaxCommercialCallsPerRun: 10,   // Ceiling on paid Level 2/3 lookups per session
        MaxTotalCallsPerRun:      50,   // Absolute ceiling on all calls
        AutoDowngradeToLevel1:    true, // Downgrade to free Level 1 validation if budget depleted
        AutoFallbackToOffline:    true, // Fall back to offline geocoding on 429/402 errors
    }),
)

metrics := client.AgentMetrics()
fmt.Printf("Total: %d, Commercial: %d, Downgraded: %d, Fallbacks: %d\n",
    metrics.TotalCalls, metrics.CommercialCalls, metrics.DowngradedCalls, metrics.OfflineFallbacks)

5. Tool Call Caching & Idempotency

Prevent redundant network calls and token spend across agent retry loops:

// Enable built-in thread-safe memory cache (1000 items, 30m TTL)
client, err := postcode.NewClient(
    postcode.WithDefaultCache(),
)

6. WebAssembly (WASM) Edge Engine

Run the entire offline validation, diagnostics, and geocoding engine inside Node.js, Deno, Bun, Cloudflare Workers, or web browsers with zero network latency (also published as @abcubed3/postcode-wasm, powering the <nipost-address-input> frontend component):

# Build WASM binary
GOOS=js GOARCH=wasm go build -ldflags="-s -w" -o wasm/postcode.wasm ./wasm

const { initPostcode } = require('./wasm/index.js');

const postcode = await initPostcode();
const result = postcode.validate("EK 01 A03 FK 01");
const loc = postcode.resolveLocation("EK 01 A03 FK 01");

7. Synthetic Address Generator & Eval Harness (postcode eval)

Benchmark AI agents, NER extractors, and LLMs against realistic Nigerian addresses with noisy landmarks, informal local descriptions, and typos:

# Benchmark baseline accuracy on 100 synthetic noisy addresses
postcode eval --samples 100 --noise 0.3

# Export synthetic dataset for Promptfoo, LangSmith, or Braintrust
postcode eval --samples 500 --export addresses.json

// Programmatic generation & evaluation
dataset := postcode.GenerateSyntheticDataset(postcode.GeneratorOptions{
    Count:     100,
    NoiseRate: 0.3,
})
result := postcode.EvaluateAgent(dataset, myAgentExtractor)
fmt.Printf("State Accuracy: %.2f%%, Postcode Accuracy: %.2f%%\n",
    result.StateAccuracy, result.PostcodeAccuracy)

8. Google Antigravity Plugin & Universal Agent Skill Bundle

This repository is packaged as an official Google Antigravity Plugin (plugin.json, mcp_config.json, rules/, skills/) adhering to the Antigravity Plugin Guidelines:

├── plugin.json                       # Official Antigravity manifest ($schema v1)
├── mcp_config.json                   # Auto-discovered MCP server definition
├── rules/
│   └── nipost-postcode.md            # Active rules for Nigerian postcode operations
└── skills/
    └── nipost-postcode/
        ├── SKILL.md                  # Domain workflow & self-healing procedures
        ├── references/               # Deep-dive manuals (grammar, levels, recovery)
        └── examples/                 # Runnable SDK, CLI, & MCP interaction patterns

Installing the Plugin

You can install and activate the plugin across all Antigravity surfaces:

1. Via Antigravity CLI Shell (agy plugin):

# Install directly from the GitHub repository URL
agy plugin install https://github.com/abcubed3/postcode

# Or install from a local cloned directory
agy plugin install ./

# Verify installation
agy plugin list

2. Inside an Interactive Session (/plugin): Run /plugin in the chat prompt to open the Plugins Manager, or install directly via inline command:

/plugin install https://github.com/abcubed3/postcode

3. Workspace-Level (Antigravity IDE & 2.0): To enable for a specific repository, add the plugin to your workspace's .agents/plugins/ directory:

mkdir -p .agents/plugins
git clone https://github.com/abcubed3/postcode.git .agents/plugins/nipost-postcode

4. Global Installation (All Projects & Workspaces): To enable across all projects on your workstation, clone into your global plugins directory:

mkdir -p ~/.gemini/config/plugins
git clone https://github.com/abcubed3/postcode.git ~/.gemini/config/plugins/nipost-postcode

What the Plugin Provides

• Auto-Configured MCP Server: Automatically connects your agent to postcode mcp using mcp_config.json.
• Cost-Aware Escalation: Enforces offline-first validation $\to$ Level 1 (Free) $\to$ Levels 2-3 (Commercial credits only when explicitly demanded).
• Informal Address Disambiguation: 5-step SOP for extracting and synthesizing postcodes from descriptive landmarks and cross-streets.
• Diagnostic Self-Healing: Automatically repairs typos and invalid segments via postcode.Diagnose.
• Reference Manuals: Grammar & States, Lookup Levels, Address Disambiguation, and Error Recovery.

Examples & Demos

Ready-to-run examples and reference integrations in the examples/ directory:

Benchmarks

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

BenchmarkParse-12             42424563        28.25 ns/op          0 B/op        0 allocs/op
BenchmarkFormatted-12        195061753         6.15 ns/op          0 B/op        0 allocs/op
BenchmarkResolveLocation-12   10245876       115.70 ns/op         32 B/op        4 allocs/op
BenchmarkGoogleMapsURL-12      3721462       325.20 ns/op        128 B/op        7 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.
• postcode.ResolveLocation: Resolves building and administrative coordinates offline in ~115 ns/op.
• postcode.GoogleMapsURL: Formats and generates universal Google Maps search URLs in ~325 ns/op.

Contributing

Contributions, bug reports, and optimizations are welcome! Please read the Contributing Guide for details on repository architecture, zero-allocation requirements, development with Taskfile, and pull request guidelines.

License

This project is licensed under the MIT License - see the LICENSE file for details.