La struttura di un indirizzo statunitense sembra semplice dall’esterno: un numero, una via, una città, un’abbreviazione dello stato e un codice postale. Proprio questa semplicità è il motivo per cui tanti moduli la gestiscono male — le parti che sembrano fisse sono esattamente quelle che portano regole, e le parti che variano sono quelle per cui nessuno lascia spazio.
Questo articolo scompone la struttura campo per campo, tratta il numero di unità e l’estensione del codice postale, e spiega perché gli indirizzi militari e territoriali esistono al di fuori dello schema che la maggior parte degli ingegneri si aspetta.
Le parti di un indirizzo statunitense
Un indirizzo postale interno è costruito da un piccolo insieme di componenti, di solito disposti su tre o quattro righe.
| Componente | Che cosa contiene | Note |
|---|---|---|
| Riga della via | Numero civico, nome della via, tipo di via, direzione | Il tipo di via fa parte del nome, non è decorazione |
| Riga dell’unità | Appartamento, suite, piano, edificio | Facoltativa, e per convenzione su una riga propria |
| Città, stato, codice postale | Città o località, codice di stato di due lettere, codice ZIP | Il codice di stato è standardizzato; non inventarne uno |
| Paese | Solo sulla posta internazionale | Omesso all’interno del paese |
La riga della via ha essa stessa un ordine interno che vale la pena conoscere: un prefisso direzionale, il nome della via, il tipo di via e un suffisso direzionale dove esiste. Il numero civico sta in testa. Quell’ordinamento è una convenzione del paese, non universale, ed è per questo che lo stesso edificio compare con il numero alla fine in altri paesi, come illustra la guida al formato degli indirizzi internazionali.
Numeri civici, tipi di via e direzioni
Il numero civico è un intero iniziale, ed è davvero un numero nel senso che i lati pari e dispari contano per la consegna — ma non è una quantità, e trattarlo come tale produce una sua propria classe di bug. Esistono intervalli, esistono suffissi alfanumerici, e una singola via può portare numeri non contigui quando attraversa confini comunali.
I tipi di via sono parole come street, avenue, road, boulevard, drive, lane o court, e normalmente seguono il nome. Gli elementi direzionali come north, south, east e west possono comparire prima del nome, dopo il tipo o in entrambe le posizioni. Scritto per esteso e abbreviato, lo stesso indirizzo ha diverse grafie corrette, ed è esattamente per questo che gli operatori postali mantengono tabelle di abbreviazioni e che un modulo dovrebbe normalizzare invece di pretendere una particolare resa.
Per i dati di test la conseguenza utile è che la riga della via è il campo con più probabilità di superare la lunghezza prevista, perché accumula in un’unica stringa un prefisso direzionale, un nome composto da più parole, un tipo di via e talvolta un qualificatore di unità.
Come si scrive il numero di un appartamento o di una suite?
Mettilo su una riga propria, oppure dopo la riga della via separato da un marcatore chiaro, ed etichettalo con la parola locale: apartment, unit, suite, floor, building. Lo stile di abbreviazione segue le stesse tabelle di convenzione del tipo di via, quindi la coerenza conta più della brevità.
La questione di modellazione è se l’unità appartenga al campo della via o a un campo proprio. Tienila separata. Un dettaglio di unità accodato alla riga della via rende la via più difficile da confrontare con qualsiasi elenco di indirizzi e impossibile da cercare in modo affidabile, ed è la prima cosa che si perde quando un campo viene troncato. Crea anche ambiguità nella direzione opposta: un numero civico e un numero di unità scritti uno dopo l’altro sembrano parte di un indirizzo stradale più lungo per qualsiasi cosa che analizzi da sinistra.
Per i casi di test rilevanti per la consegna, entrambe le varianti meritano una fixture: un indirizzo senza alcuna unità e uno con un dettaglio di unità lungo. Molti sistemi falliscono silenziosamente sul secondo.
Che cosa significano l’abbreviazione dello stato e il codice ZIP
La componente dello stato è un’abbreviazione di due lettere tratta da uno standard ufficiale, e non è un campo di testo libero. Inventare un’abbreviazione, scrivere il nome dello stato per esteso dove ci si aspetta un codice, oppure usare un codice che appartiene a un altro luogo produce dati che sembrano plausibili e falliscono più tardi. La più ampia famiglia dei codici di paese e suddivisione, e la differenza tra lo standard internazionale e gli elenchi di codici locali, è trattata nella guida ai codici ISO di paese e suddivisione.
Il codice postale è di cinque cifre, facoltativamente seguito da un’estensione di quattro cifre che restringe il codice a un gruppo di consegna più piccolo. Entrambe le forme sono valide; l’estensione è facoltativa nella pratica, e i moduli che la richiedono infastidiscono gli utenti che non conoscono la propria. Tratta l’intero valore come testo. Un codice postale è un identificatore, e gli zeri iniziali che alcune parti del paese usano scompaiono nel momento in cui una colonna numerica se ne impadronisce, come spiega diffusamente la guida ai formati dei codici postali per paese.
Il classico test di coerenza unisce i due. Un’abbreviazione dello stato che non corrisponde all’intervallo di codici postali di quello stato è uno degli errori di inserimento più comuni nei dati di indirizzo statunitensi, ed è economico da individuare.
Gli indirizzi territoriali e militari seguono le stesse regole?
In parte. Gli indirizzi nei territori statunitensi usano la stessa forma generale ma con i propri codici equivalenti allo stato e i propri intervalli di codici postali, quindi un elenco di validazione costruito solo sui cinquanta stati li respingerà pur essendo perfettamente recapitabili. Anche la posta militare ha una struttura propria, con una designazione di instradamento e un codice che svolge il ruolo di città e stato nella posta interna.
La conclusione corretta non è costruire un elenco più lungo di casi speciali codificati a mano e sperare che sia completo. È accettare che l’insieme dei codici validi è più ampio di quello familiare, ricavare l’elenco da un riferimento autorevole invece di digitarlo a mano, e far sì che la validazione fallisca in un modo che l’utente possa correggere.
Per gli sviluppatori: validare i pezzi nell’ordine giusto
Controlla i pezzi, non l’intera riga. Un’unica espressione regolare che cerca di validare un’intera stringa di indirizzo statunitense è l’errore più comune in questo campo, perché la variazione vive nella riga della via e la certezza vive nel codice di stato e nel codice postale.
Un ordine pratico: richiedi un paese così che l’insieme di regole sia noto, controlla che il codice di stato esista nell’elenco ufficiale, controlla che il codice postale corrisponda alla sua forma, poi controlla l’abbinamento tra i due. Lascia la riga della via ai controlli di lunghezza e di caratteri, e consenti a una persona di forzare un fallimento, perché un indirizzo genuinamente corretto che un verificatore non riconosce non dovrebbe essere non modificabile.
Due fixture coprono la maggior parte del rischio: un indirizzo valido sotto ogni aspetto e lo stesso indirizzo con una singola incongruenza deliberata tra stato e codice postale. Quella coppia rende evidente quando una modifica alla validazione inizia accidentalmente ad accettare tutto.
Passi successivi
Prendi un indirizzo statunitense dai tuoi dati di staging e scomponilo a mano nei suoi campi; se non sai dire in modo inequivocabile quale testo appartenga all’unità e quale alla via, le tue fixture stanno nascondendo un problema di modellazione. Poi produci un piccolo insieme di campioni statunitensi nel generatore di indirizzi e falli passare attraverso il tuo modulo, includendone uno con un dettaglio di unità lungo e uno il cui stato e codice postale discordano di proposito. Ricorda che cosa siano i campioni che passano: valori segnaposto per i test software, non posta recapitabile e non prova di dove viva qualcuno.