---
name: address-standardization
source: https://app.decimal.ai/s/address-standardization@1/SKILL.md
source_sha256: bfa77750194c
---

# 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.