What Is Address Normalization?

Raw text in. Verified address out.

Real users don't type addresses the way your database expects them. They abbreviate, misspell, swap fields, or simply write whatever comes to mind. The normalization endpoint transforms that noise into a precise, structured address — verified against the official Swiss federal register.

Spelling correction

"Zurick" becomes "Zürich". "Bahnhofstr" becomes "Bahnhofstrasse". Typos and abbreviations are resolved automatically.

Structure extraction

A single unstructured string is split into street, house number, postal code, locality, municipality, and canton — each in a dedicated field.

Federal register matching

The result is cross-referenced against the RegBL and swisstopo registers. Only real, existing Swiss addresses pass.

Confidence scoring

Every result includes a precision score. Ambiguous matches return ranked candidates so you can let the user confirm.

Data sovereignty & privacy

Your addresses stay on our Swiss infrastructure

The normalization pipeline runs end-to-end in Switzerland. Submitted addresses are not relayed to external services for inference.

Short answer: no, your address data is not sent to third-party inference services.

If you use HelvAddress, the request body is processed on our infrastructure in Switzerland. We do not forward submitted addresses to external AI providers, external geocoding services, or APIs hosted outside Switzerland for normalization.

Swiss-only normalization path
No LLM or generative model in the request flow
Clearer privacy and vendor-risk reviews

In practical terms, input understanding, locality resolution, street lookup, building-level refinement, and confidence scoring all run on our own servers in Switzerland.

Technical providers we may use for hosting or operations do not participate in the normalization engine and do not receive request bodies for AI processing or third-party enrichment.

Our infrastructure is hosted in Switzerland with Infomaniak. See: Infomaniak privacy policy

Read Privacy & Data Sovereignty
What this means for your teams

No address transfer to third-party geocoding APIs, LLMs, or generative models

Processing, operational logging, and governance remain under Swiss control

A simpler foundation for privacy, compliance, and risk reviews

Swiss-only normalization architecture Your input Free-text address HelvAddress processing in Switzerland Parsing, matching, scoring Run on our Swiss stack External services No address leaves the stack
Swiss address intelligence

Address intelligence designed for Switzerland

Normalizing a Swiss address is not just about fixing typos. You also need to handle real-world usage, abbreviations, multilingual variations, field-order inversions, and ambiguities specific to Switzerland.

Our engine turns freeform, incomplete, or imprecise input into a structured, reliable, and usable address. It also qualifies the result so your systems know when to accept it, when to ask for confirmation, and when to reject it.

1
1. Understand the input

The engine first harmonizes the writing style so it can work from a coherent baseline, even when the input is partial, noisy, or irregular.

2
2. Identify the right components

It then recognizes the useful pieces — locality, postal code, street, house number, and contextual clues — without requiring a fixed order.

3
3. Put the address back into Swiss context

The locality is resolved with Swiss geographic and linguistic realities in mind, reducing ambiguity as early as possible.

4
4. Find the street and refine the match

The street is searched in the correct territorial context, then the resolution can be refined down to the building when the data allows it.

5
5. Qualify the result

Each match is evaluated to return not just a normalized address, but also a precision level, a confidence score, and relevant alternatives when needed.

Result: a freeform address becomes consistent, production-ready data for data quality, user experience, geocoding, compliance, and operational automation.

Use Cases

Where normalization makes the difference

Every system that collects or stores Swiss addresses benefits from normalization.

E-commerce & Checkout

Customers type addresses quickly and imprecisely. Normalize at checkout to eliminate failed deliveries, reduce returns, and protect your logistics margin.

CRM & Customer Data

Imported contacts, migrated databases, or manually entered records all contain inconsistencies. A single normalization pass produces a clean, deduplicated address master.

Fraud Detection

Fraudulent orders often use slightly altered or non-existent addresses. Normalization against the federal register exposes invalid addresses that bypass simple format checks.

ERP & Logistics Systems

Route planning and parcel dispatch require structured data. Normalization converts free-text input from field agents or legacy forms into machine-readable records.

Mail & Document Services

Printed mail, invoices, and contracts must reach the right recipient. Normalize address data before generating documents to avoid undeliverable correspondence.

KYC & Onboarding

Banks, insurance companies, and fintech platforms must verify customer addresses during onboarding. Normalization against the official register provides a verifiable, timestamped proof of address validation.

Batch Job API

Normalize tens of thousands of addresses asynchronously

Submit large Swiss address files in a single API call and let HelvAddress process them in the background — without timeouts, retries, or manual intervention.

Execution priority is assigned automatically from the batch size, so small jobs return quickly while larger jobs move through dedicated queues built for high-volume data quality workflows.

LIGHT ≤ 1 000
LIGHT jobs go first

Up to 1,000 addresses. Best for quick clean-up runs, pre-import checks, and operational jobs that need results within seconds.

MEDIUM ≤ 10 000
MEDIUM jobs use a dedicated queue

Up to 10,000 addresses. Ideal for CRM exports, partner imports, and recurring database hygiene workflows.

HEAVY > 10 000
HEAVY jobs are scheduled safely

More than 10,000 addresses. Designed for large migrations and master-data remediation without putting real-time traffic at risk.

1
1. Submit one JSON payload

Send a full list of free-text Swiss addresses to the batch endpoint. HelvAddress creates a background job and assigns the right execution tier automatically.

2
2. Poll live progress

Use the status endpoint to follow progressPercent, processedItems, failedItems, and pendingItems in real time from your ERP, ETL, or back-office workflows.

3
3. Download results when ready

Once the job is completed, fetch the normalized results and feed them directly into your CRM migration, customer database clean-up, or import pipeline.

Batch submission
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"
    }
  ]
}
Live status response
{
  "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"
}
Accepted job response
{
  "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"
}
Business value

The batch API is built for teams that need Swiss address quality at scale, not just one request at a time.

Automate CRM and ERP migrations without timeout risk
Clean legacy customer files before import or deduplication
Track progress precisely for operations and support teams
API integration

Simple to integrate. Sophisticated under the hood.

Send a plain text address and receive structured JSON back. The normalization pipeline runs entirely on our Swiss infrastructure.

1
Send the raw address

POST any free-text address as plain text. No JSON wrapping, no field mapping required.

2
The engine parses & matches

Our Swiss-hosted engine tokenizes, corrects, and matches the address against official registers — without forwarding the input to external inference services.

3
Receive the structured result

Get a normalized address with all fields, a confidence score, applied corrections, and any alternative candidates.

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"
}
From ingress to response, the request body stays inside our Swiss processing environment and is not transmitted to third-party inference services.
Live Examples

See what the API does with real inputs

From casual user input to production-ready data.

Input Typo + abbreviation

bahnhofstr 1 zurick

Status: MATCHED Precision: BUILDING  ·  Score: 0.70

Bahnhofstrasse 1

8001 Zürich · ZH

Correction applied:

bahnhofstr → Bahnhofstrasse

zurick → Zürich

Input Unordered fields

1003 Lausanne, av gare 12

Status: MATCHED Precision: BUILDING  ·  Score: 0.8

Avenue de la Gare 12

1003 Lausanne · VD

Correction applied:

av gare → Avenue de la Gare

Fields reordered

Input Missing house number (ambiguous)

Route de Berne, 1000 Lausanne

Status: AMBIGUOUS Precision: 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

Status: NOT_FOUND Score: 0.00

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

API Response Structure

Everything you need in one response

The normalization response is designed to be immediately usable — no additional lookups required.

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"
}

Ready to clean your address data?

Address normalization is included in the Business plan. Try the live demo or read the API documentation to get started.

Try the Live Demo API Reference See Plans