Random Addresses for Shipping Software Testing

United States domestic zones are a function of distance between the origin and destination postal codes, resolved through the Postal Service's published zone chart at the level of the three-digit prefix. Carriers layer their own zone maps and surcharges on top, but the shape is the same everywhere: a lookup keyed on a code that has to exist. So the first property a shipping fixture needs is not realism, it is existence.

That has a practical consequence for how you choose fixtures. A rate suite that draws all its destinations from one metropolitan area tests one zone. The useful set spans the range — a few codes near the origin, a few at the far end of the country, one in a state that is expensive to reach — so that the rate table is exercised across its breaks rather than at a single point. Generating from a spread of cities is the quickest way to get that, and the postal codes come back real.

The second property is delivery type. Ordinary street mail, PO boxes, military post and single-facility codes behave differently, and the differences are exactly the branches a rate calculator gets wrong. This generator only emits codes in the first category, which is the right default: it means an unremarkable fixture is unremarkable, and the exceptional cases are ones you add deliberately rather than ones that arrive by accident in a random draw.

Label and manifest code usually has to standardise an address before it can be printed or transmitted: uppercase, punctuation removed, street suffixes and directionals abbreviated to the postal standard, secondary unit designators formatted correctly. USPS Publication 28 is the reference for the United States, and the detail worth internalising is its definition of a complete address — one carrying all the elements needed to match the Postal Service's own ZIP+4 and city-state files. It is a lookup, not a pattern, which is why standardisation code that only reformats strings passes review and fails in production.

The best test case for that code is the mismatch between the city a customer types and the city the postal file holds. It is common enough to be worth building a fixture for: our own dataset has three cities — Bloomington in Minnesota, Lakewood in Colorado and Parma in Ohio — that own no postal code under their own name, because the Postal Service files them under Minneapolis, Denver and Cleveland. A customer in Parma writes Parma; a standardiser that insists on the postal city rewrites it to Cleveland; and if your validation compares the two strings for equality, a perfectly good address is rejected.

The other standardisation cases worth having are ordinary rather than clever: a long street line that overflows the label field, a secondary unit that arrives in address line 2 on one order and appended to line 1 on the next, a name longer than the label's name field, and a city whose name contains a space or a period. None of those needs a real address to test, which is the point.

Being explicit about the gaps is more useful than pretending there are none. There is no ZIP+4 add-on: United States codes are five digits, because the four-digit extension identifies a specific delivery segment and inventing one would fabricate a delivery point rather than a fixture. There is no residential-versus-commercial flag, which matters because that classification drives real surcharges — if your code branches on it, set the flag yourself in the fixture rather than inferring it from the address.

There are no PO Box addresses and no military addresses. Both have their own formats and their own rules, both are excluded from the postal-code pools deliberately, and both are worth hand-writing as fixtures precisely because they are exceptions. Nor is there anything about the parcel: weights, dimensions, declared value and service level are your domain, and they are where most rate bugs actually live.

And a generated address will not pass a carrier's address-verification call. The postal code verifies, the city and region agree with it, and the delivery point does not exist — which is the correct outcome for a fixture and a hard limit on what it can prove. Verification paths need either a real address used with permission or your carrier's own sandbox values.

Every record starts from a real city. The region, the postal code, the telephone area code and the coordinates are all derived from that one choice, so the fields agree with one another the way a real address's fields do — rather than being drawn independently, which is how a generator ends up pairing a California city with a Michigan postal code.

United States postal codes come from the GeoNames postal dataset, published under CC BY 4.0, restricted to the codes attributed to that city and then filtered to those that take ordinary residential street mail. The filter is derived from public postal and census signals rather than licensed from the Postal Service's own delivery-type file, so it is deliberately conservative: it will drop some codes that do in fact receive street mail, which is the safer direction for a fixture.

The street name comes from a generic street-name pool rather than that city's real streets, and the house number is random between 1 and 9989. Nothing about the address is intended to resolve to a building, and that is the property that makes it safe to keep in a repository. Telephone area codes come from the same city's rate centre in the North American plan, so the phone number does not contradict the address.

The rules are enforced by tests: a postal code a city page emits must appear in that city's real list, a state page's code must fall within that state's documented ranges, and a code that takes no ordinary street mail may not appear in any pool, with two dozen verified examples pinned by name so the filter cannot silently stop working.