Address Standardization

Rewrites a free-form postal address into a single canonical mailing form. US addresses follow USPS Publication 28. The base model knows the approved abbreviations but does not apply them by default: asked to "clean up" an address it returns Title Case, spelled-out suffixes ("Street", "Avenue"), and comma separators. This skill forces the canonical form instead.

When to activate

• Clean up / tidy / standardize a mailing or shipping address.
• Make a column of addresses consistent for deduplication or record matching.
• Normalize addresses before importing into a CRM, warehouse, or label printer.

Canonical form (US — USPS Pub 28)

Apply every rule. Output is a mailing block, one element per line, in this exact order:

1. Recipient line — the name / attention line, if the input has one. Uppercase, pass through.
2. Delivery address line — PRIMARY-NUMBER [PRE-DIR] STREET-NAME SUFFIX [POST-DIR] [UNIT-DESIGNATOR UNIT-NUMBER], all on one line.
3. Last line — CITY STATE ZIP (or CITY STATE ZIP+4).

Transformation rules:

• Uppercase every character.
• Remove all punctuation — no commas, periods, or # used as a separator. The ONE retained

separator is the hyphen inside a ZIP+4.

• Street suffix → approved abbreviation. STREET→ST, AVENUE→AVE, BOULEVARD→BLVD, DRIVE→DR,

LANE→LN, ROAD→RD, COURT→CT, PLACE→PL, PLAZA→PLZ, TERRACE→TER, CIRCLE→CIR, HIGHWAY→HWY, PARKWAY→PKWY, TRAIL→TRL, WAY→WAY, SQUARE→SQ, LOOP→LOOP. Full table: see references.

• Directional → abbreviation when it leads or trails the street name. NORTH→N, SOUTH→S,

EAST→E, WEST→W, NORTHEAST→NE, NORTHWEST→NW, SOUTHEAST→SE, SOUTHWEST→SW.

• Secondary-unit designator → approved abbreviation. APARTMENT→APT, SUITE→STE, BUILDING→BLDG,

FLOOR→FL, UNIT→UNIT, ROOM→RM, DEPARTMENT→DEPT, PENTHOUSE→PH, TRAILER→TRLR. When the unit type is not stated, use # immediately before the number (e.g. # 4B).

• State → two-letter USPS code. CALIFORNIA→CA, ILLINOIS→IL, NEW YORK→NY.
• ZIP+4 is formatted as five digits, a hyphen, four digits: 62704-1234. A bare 5-digit ZIP

stays five digits.

• PO Box is written PO BOX <number>.

Worked examples

IN:  123 North Main Street, Apartment 4, Springfield, Il. 62704-1234
OUT: 123 N MAIN ST APT 4
     SPRINGFIELD IL 62704-1234

IN:  Attn: Dana Reyes; 88 southwest Grand Boulevard, Suite 210, Portland, Oregon 97205
OUT: DANA REYES
     88 SW GRAND BLVD STE 210
     PORTLAND OR 97205

IN:  P.O. Box 45, Apt. B, Reno NV 89501
OUT: PO BOX 45 # B
     RENO NV 89501

International addresses

USPS Pub 28 is US-only, and postal conventions vary by country. For a non-US address, do NOT force US suffix abbreviations or a ZIP+4 shape. Uppercase the block, keep the country's own postal-code format as written, and put the COUNTRY name on the last line. Example: a UK address keeps its outward/inward postcode (SW1A 1AA) and does not become a ZIP+4.

Deterministic bulk conversion

For large batches where identical input must map to identical output, run the converter rather than reasoning each one out: scripts/normalizer.py applies the lookup tables mechanically. The full USPS Pub 28 Appendix C1 suffix list, all directionals, and the complete secondary-unit designator table live in references/usps-pub28-abbreviations.md — consult it for a suffix or designator not shown inline above.