Address Normalizer

Parse freeform address strings into components, canonicalise them, and flag the addresses that are the same place written differently. There are zero actors in the Apify store for address normalization — the reason is that it is genuinely fiddly (four countries, four different grammars, no shared postal standard), which is exactly why it's worth having.

What it actually does

1. Parse. Splits a freeform string into unit/apartment, house number, street name, street type, city, region/state, postcode and country. Handles the very different shapes of US (123 N Main St, Apt 4, Springfield, IL 62701), UK (10 Downing Street, London SW1A 2AA), DE (Musterstraße 1, 10117 Berlin — street name first, number last) and FR (12 Rue de la Paix, 75002 Paris — number then street type then name) addresses.

2. Canonicalise. Street types and unit markers are expanded and abbreviated both ways (St ↔ Street, Rd ↔ Road, Apt/Suite/Unit, directionals like N ↔ North), casing is fixed, and postcodes are normalised per country: UK sw1a1aa → SW1A 1AA, US ZIP+4 123456789 → 12345-6789.

3. Confidence. Every parse reports a 0–1 confidence score plus which components were actually found (matched a real pattern) versus guessed (fallback heuristic, e.g. "last comma segment is probably the city").

4. Dedupe. Reuses the same fuzzy-matching core as entity-resolver and contact-deduplicator (packages/monitor-core: normalisation, Jaro-Winkler, token-set and trigram similarity, Soundex blocking, union-find clustering) scored on address-shaped fields, so 221B Baker St and 221b baker street, apt B are flagged as one duplicate group even though the unit is written as a house-number suffix in one and an explicit Apt B in the other.

5. Optional geocoding. Off by default. When turned on, parsed addresses are looked up against the free OpenStreetMap Nominatim geocoder for lat/lon. This sends a descriptive User-Agent and enforces Nominatim's usage policy of no more than 1 request/second in-process (hard floor, regardless of the configured delay), plus a per-run request cap. If geocoding is off, fails, or a query can't be built, the parsed result is still returned along with a geocodeSkippedReason explaining why — a geocoding failure never blocks the parse output.

Honest limitations

• Coverage is pattern-based, per country, not a universal postal grammar. US and UK are the most solid (mature, well-documented formats). DE and FR are best-effort: German compound street names (Bahnhofstraße) and French bis/ter suffixes are handled, but rarer regional conventions are not.
• Country detection falls back to postcode shape when no country name is present. A bare 5-digit code that isn't clearly a ZIP+4 or state+ZIP is genuinely ambiguous between US/DE/FR — it's resolved by street-type keywords when possible, and documented as "guessed" in the output otherwise.
• Junk input (empty strings, no recognisable postcode or house number) never crashes the run — it returns a low-confidence, mostly-guessed parse with warnings explaining what wasn't found.
• Nominatim is a shared free public service. Respect the 1 req/sec limit (enforced here) and set a real geocodeContact — anonymous or abusive traffic gets blocked at their end, not just yours.
• Capped at 50,000 addresses per run.