Regex & parsing · 12 min lezen
Nederlandse postcode + huisnummer parsing — de 4 edge cases die vaak misgaan
Door Alex · Gepubliceerd 24 april 2026
Een Nederlandse postcode is vier cijfers plus twee letters. Een huisnummer is een positief geheel getal, eventueel met een toevoeging. Simpel, op papier. In de praktijk gaat het vaak mis op dezelfde vier punten: varianten in huisnummer-toevoegingen, witruimte rond de postcode, de letter-uitzondering met SA/SD/SS, en het verschil tussen PostNL-notatie en BAG-registratie. Dit artikel behandelt alle vier, met een werkende TypeScript-parser en een meting tegenover Python.
1. Het postcode-formaat en de SA/SD/SS-uitzondering
PostNL definieert de Nederlandse postcode als exact vier cijfers gevolgd door twee hoofdletters — in totaal zes karakters. Het eerste cijfer mag niet nul zijn. De eenvoudige regex /^[1-9][0-9]{3}[A-Z]{2}$/ vangt dat af. Maar er is een historische uitzondering die veel validators overslaan: er bestaan geen postcodes waarvan de twee letters SA, SD of SS zijn. Die combinaties zijn bij de invoering van het postcodesysteem in 1977 bewust weggelaten om associatie met de SS (Schutzstaffel), de SD (Sicherheitsdienst) en de SA (Sturmabteilung) te voorkomen.
Er is geen postcode in gebruik die eindigt op SA, SD of SS. Op elk van de 9000 mogelijke cijfercombinaties zijn daarmee drie van de 676 lettercombinaties uitgesloten. Een parser die die uitzondering toepast, wijst per definitie geen legitieme invoer af, en houdt wel een deel van de onzin-invoer tegen voordat die de verzendflow bereikt.
// Strict: vier cijfers + twee letters, eerste cijfer != 0,
// letters mogen geen SA/SD/SS zijn.
const POSTCODE_STRICT = /^[1-9][0-9]{3}(?!SA|SD|SS)[A-Z]{2}$/;
POSTCODE_STRICT.test('1234AB'); // true
POSTCODE_STRICT.test('1012SA'); // false — uitgesloten combinatie
POSTCODE_STRICT.test('0123AB'); // false — mag niet met 0 beginnenDe negatieve lookahead (?!SA|SD|SS) staat direct na de vier cijfers: op die positie kijkt hij vooruit naar de twee letters zonder ze te consumeren. Daarna matcht [A-Z]{2} de letters zelf.
Een alternatief is de lookahead weglaten en de drie combinaties apart afvangen met een Set. Dat is net zo correct, en in Go de enige optie (RE2 kent geen lookahead). In onze meting in Node kostte die tweede stap per miljoen postcodes zo'n 20 milliseconden extra: meetbaar, maar ook bij een batch-import verwaarloosbaar.
2. Postcode-spaties: zeven varianten in invoer
PostNL schrijft de postcode officieel met een spatie tussen cijfers en letters: 1234 AB. In invoer, databases en koppelingen kom je onder meer deze varianten tegen:
1234AB // zonder spatie
1234 AB // officiële schrijfwijze, één spatie
1234 AB // dubbele spatie
1234\tAB // tab
1234ab // kleine letters
1234-AB // streepje
1234AB // spatie ervoor (copy-paste)De pragmatische aanpak: normaliseer altijd voor je valideert. Trim, zet om naar hoofdletters en verwijder spaties en streepjes. Bewaar daarna intern de gecanoniceerde vorm (geen spaties) en render bij output de spatie-vorm terug.
export function normalizePostcode(input: string): string | null {
const cleaned = input
.trim()
.toUpperCase()
.replace(/[\s-]+/g, '');
return POSTCODE_STRICT.test(cleaned) ? cleaned : null;
}
export function formatPostcode(canonical: string): string {
// '1234AB' → '1234 AB'
return `${canonical.slice(0, 4)} ${canonical.slice(4)}`;
}Bewaar intern altijd de gecanoniceerde vorm, niet de invoer-vorm. Zoekindexen, deduplicatie en verzendintegraties gaan dan op één canonieke string werken. De kosten van heen-en-weer formatteren op presentatie-niveau zijn verwaarloosbaar vergeleken met de kosten van dubbele klantrecords.
3. Huisnummer-toevoegingen: dertien varianten in invoer
Een huisnummer is een getal. Tot zover simpel. De toevoeging is waar het spant. In de Basisregistratie Adressen en Gebouwen (BAG) bestaat een adres uit een huisnummer, een optionele huisletter en een optionele huisnummertoevoeging, maar in invoer zie je die delen op veel manieren gecombineerd. Varianten die een parser moet afhandelen:
10 // geen toevoeging
10A // huisletter direct erachter
10a // huisletter als kleine letter
10-A // streepje
10 A // spatie
10A1 // huisletter + toevoeging
10-1 // streepje + nummer
10/2 // slash + nummer
10 hs // hs = huis (benedenwoning)
10 I // Romeins cijfer voor de verdieping
10 II // tweede verdieping
10-III // derde verdieping, met streepje
10 bis // bisAl die varianten kom je in invoer tegen. Door ze te splitsen in huisnummer (integer) en toevoeging (string, genormaliseerd) kun je ze vergelijken met de BAG en doorgeven aan verzendkoppelingen die die velden apart vragen.
Een paar minder bekende details die impact hebben op je parser. Een huisnummer is in de BAG altijd een getal van 1 tot en met 99.999. Een huisletter is één letter, en mag een hoofdletter of een kleine letter zijn. De huisnummertoevoeging bestaat uit maximaal vier letters en/of cijfers; streepjes en slashes horen er in de BAG niet bij. Qua lengte passen III en bis dus wel en eerste of 2 hoog niet. Wel is het volgens de Praktijkhandleiding BAG niet de bedoeling dat een toevoeging uit Romeinse cijfers bestaat. De postcode validator past deze grenzen toe op één adres of een hele lijst.
4. PostNL-notatie versus BAG-registratie
BAG splitst een adres in drie velden: huisnummer (integer, 1–99999), huisletter (één letter, optioneel) en huisnummertoevoeging (maximaal vier tekens, optioneel). De verzend-API van PostNL kent daarentegen één gecombineerd HouseNrExt veld naast het numerieke huisnummer.
Dat verschil veroorzaakt drie veel-voorkomende bugs:
- 10A parsing: BAG-conform is dit huisnummer
10+ huisletterA+ toevoegingnull. Voor PostNL wordt datHouseNr=10, HouseNrExt=A. Als je het niet splitst, stuurt je systeemHouseNr="10A"naar een veld dat een nummer verwacht; afhankelijk van de koppeling levert dat een foutmelding of een verkeerd adres op. - 10 I: in de adresnotatie is dit meestal huisnummer
10op de eerste verdieping, met toevoegingIen géén huisletter. In de BAG is een Romeinse toevoeging niet de bedoeling, dus daar staat de verdieping waarschijnlijk anders geregistreerd. Een naïeve regex vangt dit als huisnummer10en huisletterI. Bij adresvalidatie tegen de BAG geeft dat een mismatch: het adres bestaat wel, maar niet zoals jouw systeem het voorstelt. - 10 hs:"huis", de benedenwoning; vooral bekend uit Amsterdam. Hoort altijd in de toevoeging, nooit in de huisletter. Een parser die alleen een losse letter als toevoeging verwacht, weigert dit adres.
De oplossing is parsen naar het BAG-model intern, en converteren naar het PostNL-model pas bij verzending.
5. Werkende TypeScript parser
De volgende implementatie splitst een adresregel in postcode, huisnummer, huisletter en toevoeging volgens het BAG-model. Geen externe dependencies, werkt in Node, Bun, Deno en browsers.
// src/lib/address-parser.ts
export const POSTCODE_STRICT = /^[1-9][0-9]{3}(?!SA|SD|SS)[A-Z]{2}$/;
export type BagAddress = {
postcode: string; // '1234AB' canonical
huisnummer: number; // 1..99999
huisletter: string | null;
toevoeging: string | null;
};
const ROMEINS = /^[IVX]+$/;
// 1–5 cijfers (geen zesde erachter), daarna de rest van de invoer
const HUISNUMMER_PATTERN = /^(\d{1,5})(?!\d)(.*)$/;
export function parseAddress(
postcodeInput: string,
huisnummerInput: string,
): BagAddress | null {
// 1. Postcode normaliseren.
const postcode = postcodeInput
.trim()
.toUpperCase()
.replace(/[\s-]+/g, '');
if (!POSTCODE_STRICT.test(postcode)) return null;
// 2. Huisnummer afsplitsen.
const match = HUISNUMMER_PATTERN.exec(huisnummerInput.trim());
if (!match) return null;
const nr = Number(match[1]);
if (nr < 1 || nr > 99999) return null;
// 3. De rest opdelen in letter- en cijferblokken: 'A1' → ['A', '1'].
const rest = match[2];
if (!/^[A-Za-z0-9\s\-/]*$/.test(rest)) return null;
const delen = rest.match(/[A-Za-z]+|\d+/g) ?? [];
let huisletter: string | null = null;
const toevoegingen: string[] = [];
for (const [i, deel] of delen.entries()) {
const upper = deel.toUpperCase();
if (i === 0 && /^[A-Z]$/.test(upper) && !ROMEINS.test(upper)) {
// Eén losse letter direct na het nummer = BAG-huisletter.
huisletter = upper;
} else {
// Al het andere (hs, bis, II, 2) hoort in de toevoeging.
toevoegingen.push(ROMEINS.test(upper) ? upper : deel.toLowerCase());
}
}
const toevoeging = toevoegingen.length > 0 ? toevoegingen.join(' ') : null;
return { postcode, huisnummer: nr, huisletter, toevoeging };
}Twee bewuste keuzes: één losse letter direct na het nummer wordt de huisletter, behalve I, V en X; die leest de parser als Romeins cijfer voor de verdieping. Woorden als hs, bg, bis en sous gaan altijd naar de toevoeging. Romeinse cijfers blijven hoofdletters; alle andere toevoegingen worden kleine letters, zodat deduplicatie consistent is. Vergelijk huisletter en toevoeging daarom hoofdletterongevoelig met de BAG.
6. Unit tests voor alle edge cases
// src/lib/address-parser.test.ts
import { describe, it, expect } from 'vitest';
import { parseAddress } from './address-parser';
describe('parseAddress', () => {
it.each([
['1234AB', '10', { huisnummer: 10, huisletter: null, toevoeging: null }],
['1234 AB', '10', { huisnummer: 10, huisletter: null, toevoeging: null }],
['1234ab', '10A', { huisnummer: 10, huisletter: 'A', toevoeging: null }],
['1234AB', '10a', { huisnummer: 10, huisletter: 'A', toevoeging: null }],
['1234 AB', '10-A', { huisnummer: 10, huisletter: 'A', toevoeging: null }],
['1234AB', '10 A', { huisnummer: 10, huisletter: 'A', toevoeging: null }],
['1234AB', '10A1', { huisnummer: 10, huisletter: 'A', toevoeging: '1' }],
['1234AB', '10-1', { huisnummer: 10, huisletter: null, toevoeging: '1' }],
['1234AB', '10/2', { huisnummer: 10, huisletter: null, toevoeging: '2' }],
['1234AB', '10 hs', { huisnummer: 10, huisletter: null, toevoeging: 'hs' }],
['1234AB', '10 I', { huisnummer: 10, huisletter: null, toevoeging: 'I' }],
['1234AB', '10 II', { huisnummer: 10, huisletter: null, toevoeging: 'II' }],
['1234AB', '10-III', { huisnummer: 10, huisletter: null, toevoeging: 'III' }],
['1234AB', '10 bis', { huisnummer: 10, huisletter: null, toevoeging: 'bis' }],
])('parst %s %s correct', (pc, nr, expected) => {
const result = parseAddress(pc, nr);
expect(result).toMatchObject(expected);
expect(result?.postcode).toBe('1234AB');
});
it('verwerpt postcode 1012SA', () => {
expect(parseAddress('1012SA', '10')).toBeNull();
});
it('verwerpt postcode 0123AB', () => {
expect(parseAddress('0123AB', '10')).toBeNull();
});
it('verwerpt huisnummer 0', () => {
expect(parseAddress('1234AB', '0')).toBeNull();
});
it('verwerpt huisnummer > 99999', () => {
expect(parseAddress('1234AB', '100000')).toBeNull();
});
});Deze testset dekt alle dertien varianten uit sectie 3, de SA/SD/SS-uitzondering, de 0-prefix-regel en de bovengrens van 99.999.
7. Benchmark: TypeScript versus Python
Gemeten op een laptop met een Intel Core i7-14650HX (Windows 11): 1 miljoen invoerregels, een mix van de varianten uit sectie 2 en 3 inclusief ongeldige invoer, geparsed met dezelfde logica in TypeScript (Node 22.13) en Python 3.12 met re. De resultaten blijven in het geheugen, zoals bij een batch-import; beste van drie runs:
| Taal | Totaaltijd | Per adres | Geheugen (RSS piek) |
|---|---|---|---|
| TypeScript (Node 22.13) | ~0,36 s | ~0,36 µs | ~260 MB |
| Python 3.12 (re) | ~1,3 s | ~1,3 µs | ~215 MB |
Node is in deze meting bijna vier keer zo snel: V8 compileert zowel de code als de regexen naar machinecode. Python gebruikte in deze opzet iets minder geheugen (piek van het hele proces, inclusief de invoer).
Voor een webshop met 10.000 orders per dag is de taalkeuze hier irrelevant: ook de langzaamste variant verwerkt ruim 700.000 adressen per seconde.
8. Fouten die vaak voorkomen
Deze patronen zie je terug in adresformulieren en koppelingen:
- Toevoegingen geweigerd: adressen met toevoeging
hsofbgworden geweigerd, omdat het formulier alleen een losse letter als toevoeging verwacht. - Niet-bestaande postcode geaccepteerd: invoer
1012SAgaat zonder foutmelding door en valt pas om bij de verzendkoppeling. - Geen normalisatie bij opslag: dubbele klantrecords, omdat de klant zijn postcode de ene keer met en de andere keer zonder spatie invoert.
- Weer aan elkaar geplakt: huisnummer en toevoeging gaan als één veld naar de vervoerder, waardoor een toevoeging als
IIverloren kan gaan of verkeerd wordt gelezen.
Het patroon is dat het niet één bug is maar een opeenstapeling van kleine normalisatie- en validatie-stappen die allemaal ontbreken. Goed gesplitst modelleren bij invoer, en één keer correct converteren bij output, lost alle vier in één pass op.
9. Bronnen en referenties
- PostNL — Postcodesysteem en schrijfwijze. Officiële schrijfwijze is "1234 AB" met exact één spatie.
- Kadaster — Basisregistratie Adressen en Gebouwen (BAG) Informatiemodel, versie 2.0. Definieert de velden
huisnummer,huisletterenhuisnummertoevoegingmet bijbehorende eisen aan lengte en tekens; zie ook de Praktijkhandleiding BAG. - NEN 5825 — Nederlandse norm voor de notatie van adressen.
- Wikipedia — Postcodes in Nederland, over de invoering in 1977 en de uitgesloten lettercombinaties.
Gerelateerde tools
- Postcode Generator — genereer fictieve NL postcodes, eventueel met huisnummer en toevoeging
- Postcode Validator — splitst huisnummer, huisletter en toevoeging volgens de BAG
- Nederlandse postcode-regex in vijf talen — dezelfde regex-logica toegepast op JavaScript, Python, PHP, Go en C#
- Dataset Generator — adressen met postcode, straat, huisnummer en plaats in één export