Cos'è la normalizzazione degli indirizzi?

Testo grezzo in entrata. Indirizzo verificato in uscita.

Gli utenti reali non digitano gli indirizzi come li aspetta il vostro database. Abbreviano, fanno errori, invertono i campi o scrivono semplicemente ciò che viene loro in mente. L'endpoint di normalizzazione trasforma quel rumore in un indirizzo preciso e strutturato — verificato contro il registro federale ufficiale svizzero.

Correzione ortografica

"Zuriga" diventa "Zurigo". "Bahnhofstr" diventa "Bahnhofstrasse". Errori tipografici e abbreviazioni vengono risolti automaticamente.

Estrazione della struttura

Una stringa non strutturata viene suddivisa in via, numero civico, NPA, località, comune e cantone — ognuno in un campo dedicato.

Corrispondenza registro federale

Il risultato viene incrociato con i registri RegBL e swisstopo. Solo gli indirizzi svizzeri reali ed esistenti superano la verifica.

Punteggio di confidenza

Ogni risultato include un punteggio di precisione. Le corrispondenze ambigue restituiscono candidati classificati per consentire all'utente di confermare.

Sovranità dei dati & privacy

I vostri indirizzi restano sulla nostra infrastruttura svizzera

La pipeline di normalizzazione viene eseguita end-to-end in Svizzera. Gli indirizzi inviati non vengono inoltrati a servizi esterni per l'inferenza.

Risposta breve: no, i vostri dati di indirizzo non vengono inviati a servizi di inferenza di terze parti.

Se usate HelvAddress, il corpo della richiesta viene elaborato sulla nostra infrastruttura in Svizzera. Non inoltriamo gli indirizzi inviati a fornitori AI esterni, a servizi di geocodifica di terze parti o ad API ospitate fuori dalla Svizzera per la normalizzazione.

Percorso di normalizzazione solo svizzero
Nessun LLM o modello generativo nel flusso di richiesta
Revisioni privacy e rischio fornitore più semplici

In pratica, comprensione dell'input, risoluzione della località, ricerca della via, affinamento fino all'edificio e punteggio di affidabilità vengono eseguiti sui nostri server in Svizzera.

Gli eventuali fornitori tecnici utilizzati per hosting o operazioni non partecipano al motore di normalizzazione e non ricevono i corpi delle richieste per elaborazioni AI o arricchimenti di terze parti.

La nostra infrastruttura è ospitata in Svizzera presso Infomaniak. Vedi: l’informativa sulla privacy di Infomaniak

Leggi Privacy & Data Sovereignty
Cosa significa per i vostri team

Nessun trasferimento di indirizzi verso API di geocodifica, LLM o modelli generativi di terze parti

Elaborazione, logging operativo e governance restano sotto controllo svizzero

Una base più semplice per privacy, conformità e revisioni del rischio

Architettura di normalizzazione solo svizzera Il vostro input Indirizzo in testo libero Elaborazione HelvAddress in Svizzera Analisi, matching, scoring Sul nostro stack svizzero Servizi esterni Nessun indirizzo esce dallo stack
Intelligenza d'indirizzo svizzera

Un'intelligenza d'indirizzo pensata per la Svizzera

Normalizzare un indirizzo svizzero non significa solo correggere un refuso. Bisogna anche gestire usi reali, abbreviazioni, variazioni multilingui, inversioni dell'ordine dei campi e ambiguità specifiche del territorio svizzero.

Il nostro motore trasforma un input libero, incompleto o impreciso in un indirizzo strutturato, affidabile e utilizzabile. Inoltre qualifica il risultato, così i vostri sistemi sanno quando accettare, quando chiedere conferma e quando rifiutare.

1
1. Comprendere l'input

Il motore armonizza prima la scrittura per lavorare su una base coerente, anche quando l'input è parziale, rumoroso o irregolare.

2
2. Identificare i componenti giusti

Poi riconosce gli elementi utili — località, NPA, via, numero civico e indizi contestuali — senza richiedere un ordine fisso.

3
3. Rimettere l'indirizzo nel contesto svizzero

La località viene risolta tenendo conto delle realtà geografiche e linguistiche svizzere, così da ridurre le ambiguità il prima possibile.

4
4. Trovare la via e affinare la corrispondenza

La via viene cercata nel corretto contesto territoriale e, quando i dati lo consentono, la risoluzione può essere affinata fino al livello dell'edificio.

5
5. Qualificare il risultato

Ogni corrispondenza viene valutata per restituire non solo un indirizzo normalizzato, ma anche un livello di precisione, un punteggio di fiducia e alternative pertinenti quando necessario.

Risultato: un indirizzo libero diventa un dato coerente e pronto per la produzione, utile per data quality, user experience, geocodifica, conformità e automazione operativa.

Casi d'uso

Dove la normalizzazione fa la differenza

Ogni sistema che raccoglie o archivia indirizzi svizzeri beneficia della normalizzazione.

E-commerce & Checkout

I clienti digitano gli indirizzi rapidamente e imprecisamente. Normalizzate al checkout per eliminare le consegne fallite, ridurre i resi e proteggere il vostro margine logistico.

CRM & Dati clienti

Contatti importati, database migrati o record inseriti manualmente contengono tutti inconsistenze. Un singolo passaggio di normalizzazione produce un riferimento indirizzi pulito e deduplicato.

Rilevamento frodi

Gli ordini fraudolenti usano spesso indirizzi leggermente alterati o inesistenti. La normalizzazione contro il registro federale espone gli indirizzi non validi che aggirano i semplici controlli di formato.

ERP & Sistemi logistici

La pianificazione dei percorsi e la spedizione di pacchi richiedono dati strutturati. La normalizzazione converte gli input in testo libero dagli agenti di campo o dai moduli legacy in record leggibili da macchina.

Posta & Servizi documentali

La posta stampata, le fatture e i contratti devono raggiungere il destinatario giusto. Normalizzate prima di generare i documenti per evitare corrispondenza non consegnabile.

KYC & Onboarding

Banche, assicurazioni e piattaforme fintech devono verificare gli indirizzi dei clienti durante l'onboarding. La normalizzazione contro il registro ufficiale fornisce una prova verificabile e con marca temporale della validazione dell'indirizzo.

Batch Job API

Normalizzate in asincrono decine di migliaia di indirizzi

Inviate grandi liste di indirizzi svizzeri con una sola chiamata API e lasciate che HelvAddress li elabori in background — senza timeout, retry manuali o interventi operativi.

La priorità di esecuzione viene assegnata automaticamente in base alla dimensione del lotto, così i job piccoli tornano rapidamente mentre i volumi più grandi passano in code dedicate pensate per workflow di data quality ad alto volume.

LIGHT ≤ 1 000
I job LIGHT passano per primi

Fino a 1'000 indirizzi. Ideale per pulizie rapide, controlli pre-import e attività operative con risultati in pochi secondi.

MEDIUM ≤ 10 000
I job MEDIUM hanno una coda dedicata

Fino a 10'000 indirizzi. Perfetto per export CRM, import partner e routine ricorrenti di igiene del database.

HEAVY > 10 000
I job HEAVY sono pianificati in sicurezza

Oltre 10'000 indirizzi. Progettato per grandi migrazioni e remediation dei dati master senza mettere a rischio il traffico real-time.

1
1. Inviate un payload JSON

Inviate un elenco completo di indirizzi svizzeri in testo libero al endpoint batch. HelvAddress crea un job in background e assegna automaticamente il giusto livello di priorità.

2
2. Monitorate il progresso in tempo reale

Usate il endpoint di stato per seguire `progressPercent`, `processedItems`, `failedItems` e `pendingItems` in tempo reale dai vostri workflow ERP, ETL o back-office.

3
3. Scaricate i risultati quando sono pronti

Quando il job è completato, recuperate i risultati normalizzati e re-inseriteli direttamente nelle migrazioni CRM, nella pulizia anagrafiche o nei pipeline di import.

Invio del batch
POST /api/jobs/normalize
Authorization: Bearer {access_token}
Content-Type: application/json
X-HelvAddress-API-Version: 1.0.0

{
  "items": [
    {
      "id": "row-001",
      "address": "Bahnhofstr 1, 8001 zurich"
    },
    {
      "id": "row-002",
      "address": "1003 Lausanne, av gare 12"
    },
    {
      "id": "row-003",
      "address": "Grand- 22, 1470 Estavayer-le-Lac"
    }
  ]
}
Risposta di stato
{
  "jobId": "8a5f2b0d-4f1f-4a48-85d7-b8d6bca2e840",
  "status": "PROCESSING",
  "level": "LIGHT",
  "totalItems": 3,
  "processedItems": 2,
  "failedItems": 0,
  "pendingItems": 1,
  "progressPercent": 66.67,
  "createdAt": "2026-03-22T10:00:00Z",
  "startedAt": "2026-03-22T10:00:02Z"
}
Risposta di accettazione
{
  "jobId": "8a5f2b0d-4f1f-4a48-85d7-b8d6bca2e840",
  "level": "LIGHT",
  "totalItems": 3,
  "statusUrl": "/api/jobs/8a5f2b0d-4f1f-4a48-85d7-b8d6bca2e840",
  "resultsUrl": "/api/jobs/8a5f2b0d-4f1f-4a48-85d7-b8d6bca2e840/results"
}
Valore business

La Batch Job API è pensata per i team che devono garantire qualità degli indirizzi svizzeri su larga scala, non solo richiesta per richiesta.

Automatizzare migrazioni CRM ed ERP senza rischio di timeout
Pulire file clienti legacy prima di import o deduplicazione
Monitorare l'avanzamento con precisione per operations e supporto
Integrazione API

Semplice da integrare. Sofisticato sotto il cofano.

Inviate un indirizzo in testo semplice e ricevete JSON strutturato. La pipeline di normalizzazione viene eseguita interamente sulla nostra infrastruttura svizzera.

1
Inviate l'indirizzo grezzo

POST di qualsiasi indirizzo come testo semplice. Nessun wrapping JSON, nessun mapping di campi richiesto.

2
Il motore analizza e corrisponde

Il nostro motore ospitato in Svizzera tokenizza, corregge e abbina l'indirizzo ai registri ufficiali — senza inoltrare l'input a servizi di inferenza esterni.

3
Ricevete il risultato strutturato

Ottenete un indirizzo normalizzato con tutti i campi, un punteggio di confidenza, le correzioni applicate e gli eventuali candidati alternativi.

Request
POST /api/addresses/normalize
Authorization: Bearer {access_token}
Content-Type: text/plain
X-HelvAddress-API-Version: 1.0.0

Grand- 22, 1470 Estavayer-le-Lac
Response
{
  "status": "MATCHED",
  "best": {
    "score": 0.85,
    "precision": "BUILDING",
    "normalized": {
      "streetName": "Grand-Rue",
      "houseNumber": "22",
      "zip4": 1470,
      "zipa": 0,
      "locality": "Estavayer-le-Lac",
      "municipality": "Estavayer",
      "lines": [
        "Grand-Rue 22",
        "1470 Estavayer-le-Lac"
      ]
    },
    "changes": [
      {
        "field": "STREET_NAME",
        "from": "Grand",
        "to": "Grand-Rue",
        "type": "STREET_TYPE_CORRECTION",
        "impact": 0.1
      }
    ],
    "meta": {
      "egaid": 101045004,
      "canton": "FR"
    }
  },
  "candidates": [],
  "issues": [],
  "dataVersion": "2026-03-14"
}
Dall'ingresso alla risposta, il corpo della richiesta resta nel nostro ambiente di elaborazione svizzero e non viene trasmesso a servizi di inferenza di terze parti.
Esempi pratici

Guardate cosa fa l'API con input reali

Dall'input grezzo dell'utente ai dati pronti per la produzione.

Input Typo + abbreviation

bahnhofstr 1 zurick

Stato: MATCHED Precisione: BUILDING  ·  Punteggio: 0.70

Bahnhofstrasse 1

8001 Zürich · ZH

Correzione applicata:

bahnhofstr → Bahnhofstrasse

zurick → Zürich

Input Unordered fields

1003 Lausanne, av gare 12

Stato: MATCHED Precisione: BUILDING  ·  Punteggio: 0.8

Avenue de la Gare 12

1003 Lausanne · VD

Correzione applicata:

av gare → Avenue de la Gare

Fields reordered

Input Missing house number (ambiguous)

Route de Berne, 1000 Lausanne

Stato: AMBIGUOUS Precisione: STREET

Multiple candidates returned — user confirmation recommended

Route de Berne 1, 1000 Lausanne

Route de Berne 2, 1000 Lausanne

Route de Berne 6, 1000 Lausanne

...

Input Entirely made-up address

Rue du Château 99, 9999 Fakestadt

Stato: NOT_FOUND Punteggio: 0.00

No match found in the Swiss federal register. This address does not exist — ideal signal for fraud detection or data quality workflows.

Struttura della risposta API

Tutto ciò di cui avete bisogno in un'unica risposta

La risposta di normalizzazione è progettata per essere immediatamente utilizzabile — senza lookup aggiuntivi.

Field Type Description
statusstringMATCHED · AMBIGUOUS · NOT_FOUND · INVALID_INPUT · INTERNAL_ERROR
bestobjectBest candidate when a reliable match exists
best.scorefloatMatch confidence from 0.0 to 1.0
best.precisionstringPOSTAL · STREET · BUILDING
best.normalizedobjectStructured normalized Swiss address
best.changesarrayField-level changes applied during normalization
candidatesarrayAlternative candidates returned when status is AMBIGUOUS
issuesarrayWarnings explaining uncertainty or parsing limits
dataVersionstringBuilding datasource version used for matching
Status values

MATCHED Unique, high-confidence result

AMBIGUOUS Multiple candidates — present choices to user

NOT_FOUND No match in federal register

INVALID_INPUT Input could not be parsed reliably

INTERNAL_ERROR Unexpected server-side normalization failure

Full response example
{
  "status": "MATCHED",
  "best": {
    "score": 0.9812,
    "precision": "BUILDING",
    "normalized": {
      "streetName": "Bahnhofstrasse",
      "houseNumber": "1",
      "zip4": 8001,
      "zipa": 0,
      "locality": "Zürich",
      "municipality": "Zürich",
      "lines": [
        "Bahnhofstrasse 1",
        "8001 Zürich"
      ],
      "lat": 47.376887,
      "lng": 8.541694
    },
    "changes": [
      {
        "field": "STREET_NAME",
        "from": "bahnhofstr",
        "to": "Bahnhofstrasse",
        "type": "ABBREVIATION_EXPANSION",
        "impact": 0.03
      },
      {
        "field": "CITY",
        "from": "zurick",
        "to": "Zürich",
        "type": "SPELLING_CORRECTION",
        "impact": 0.02
      }
    ],
    "meta": {
      "egaid": 100497285,
      "canton": "ZH"
    }
  },
  "candidates": [],
  "issues": [],
  "dataVersion": "2026-03-14"
}

Pronti a pulire i vostri dati di indirizzo?

La normalizzazione degli indirizzi è inclusa nel piano Business. Provate la demo live o leggete la documentazione API per iniziare.

Prova la Demo Riferimento API Vedere i piani