Go SDK for Postio — the UK validation API for
addresses, emails and phone numbers. Stdlib net/http only, zero
dependencies. Backed by Royal Mail PAF and Ordnance Survey.
First time? Sign up free — first 100 lookups on us, no card needed.
go get github.com/postio-uk/postio-goRequires Go 1.22+.
package main
import (
"context"
"fmt"
"log"
"github.com/postio-uk/postio-go"
)
func main() {
client, err := postio.NewClient(postio.WithAPIKey("pk_..."))
if err != nil {
log.Fatal(err)
}
result, err := client.Address.Search(context.Background(), "downing street", nil)
if err != nil {
log.Fatal(err)
}
for _, hit := range result.Results {
fmt.Println(hit.UDPRN, hit.Suggestion)
}
fmt.Println("request id:", result.Meta.RequestID)
}API key may also come from POSTIO_API_KEY.
| Method | Returns |
|---|---|
client.Address.Search(ctx, q, opts) |
*AddressSearchEnvelope |
client.Address.Postcode(ctx, postcode, opts) |
*AddressPostcodeEnvelope |
client.Address.UDPRN(ctx, udprn) |
*AddressUDPRNEnvelope |
client.Email.Validate(ctx, address) |
*EmailEnvelope |
client.Phone.Validate(ctx, number) |
*PhoneEnvelope |
client.Connect(ctx) |
*ConnectSuccess |
opts may be nil for default behaviour. Every method takes a
context.Context for cancellation/timeout — pass context.Background()
if you don't have one.
Every non-2xx response returns a *postio.Error. Match by sentinel
with errors.Is, or by struct with errors.As for full detail.
result, err := client.Address.Postcode(ctx, "not-a-postcode", nil)
if errors.Is(err, postio.ErrValidation) {
var e *postio.Error
errors.As(err, &e)
fmt.Printf("validation failed (request_id=%s): %s\n", e.RequestID, e.Details)
}| Sentinel | HTTP |
|---|---|
postio.ErrValidation |
400 / 422 |
postio.ErrInvalidKey |
401 |
postio.ErrOutOfCredit |
402 |
postio.ErrForbidden |
403 |
postio.ErrNotFound |
404 |
postio.ErrRateLimit |
429 (.RetryAfter populated when sent) |
postio.ErrServer |
5xx |
postio.ErrTimeout |
local request timeout |
postio.ErrConnection |
transport error |
The *Error struct exposes Status, Code, Message, Details,
RequestID, RetryAfter, the raw Envelope, and a Cause wrapping
the underlying transport error.
client, err := postio.NewClient(
postio.WithAPIKey("pk_..."),
postio.WithBaseURL("https://api.postio.co.uk/v1"), // default
postio.WithTimeout(10 * time.Second), // default
postio.WithRetries(2), // default; 0 to disable
postio.WithRetryBackoff(500*time.Millisecond, 8*time.Second),
postio.WithHeader("x-tracking-id", "..."),
)Default retry policy: 2 retries on 408/409/429/5xx + network/timeout, exponential backoff with full jitter (500ms → 8s cap).
MIT — see LICENSE.
Postio is a trading name of Onno Group Limited, registered in England & Wales (company no. 08622799). Registered office: Suite 22 Trym Lodge, 1 Henbury Road, Westbury-On-Trym, Bristol BS9 3HQ.