A small, fast Rust HTTP service for Indian pincode lookup. Response shape mirrors api.postalpincode.in so existing clients are drop-in compatible. The full post-office dataset (~165 k offices across ~19 k pincodes) is embedded into the binary at build time and held in an in-memory HashMap for O(1) lookups.

docker run --rm -p 8080:8080 ghcr.io/knutties/pincode-rs:latest

curl http://127.0.0.1:8080/pincode/560076 | jq

cargo run --release

docker compose up --build

code must be six ASCII digits with the first digit in 1–8 (Indian pincode format).

curl -s http://127.0.0.1:8080/pincode/560076 | jq

[
  {
    "Message": "Number of pincode(s) found: 4",
    "Status": "Success",
    "PostOffice": [
      {
        "Name": "Bannerghatta Road",
        "Description": null,
        "BranchType": "Sub Post Office",
        "DeliveryStatus": "Delivery",
        "Circle": "Karnataka",
        "District": "Bengaluru Urban",
        "Division": "Bengaluru South",
        "Region": "Bengaluru HQ",
        "Block": "Bengaluru Urban",
        "State": "Karnataka",
        "Country": "India",
        "Pincode": "560076"
      }
    ]
  }
]

Response codes:

All /pincode/{code} responses set Cache-Control: public so a reverse proxy or CDN can cache them; the TTL is left to the cache layer.

curl -s http://127.0.0.1:8080/health

{ "status": "ok", "pincodes": 19586, "post_offices": 165627 }

/health always sets Cache-Control: no-store so liveness signals reflect live state.

The service does no path-prefix introspection — mount it behind any reverse-proxy prefix you like.

cargo test

22 tests total: 11 library unit tests (normalization helpers, CSV loader, response DTOs, error envelope) and 11 integration tests (full request/response over the real embedded CSV via tower::ServiceExt::oneshot).

Multi-arch images (linux/amd64 + linux/arm64) are published to GitHub Container Registry:

ghcr.io/knutties/pincode-rs:latest
ghcr.io/knutties/pincode-rs:vYYYYMMDD.HHMM   # CalVer, UTC
ghcr.io/knutties/pincode-rs:sha-<short>      # commit SHA

latest always points to the most recent build from main. Each push to main also creates a matching git tag in this repo.

• Design spec: docs/superpowers/specs/2026-05-22-pincode-service-design.md
• Implementation plan: docs/superpowers/plans/2026-05-22-pincode-service.md