Address Validation as a Conversation Design Problem

When a tradesperson types "Musterstr. 3 Frankfurt" into Kaepsi, should the system accept it, correct it, or reject it? The answer depends on context, and getting it wrong has real consequences. An invoice delivered to the wrong address is a problem for everyone in the chain.

The Three-Stage Approach

Our address validation runs in three stages, each with a distinct purpose.

Stage 1: Format check. Before touching any external API, the system asks Claude to evaluate whether the input looks like a genuine postal address: does it contain a street name, a house number, a postal code, and a city? This check is fast and inexpensive, and it rejects obviously malformed inputs before they consume geocoding quota.

Stage 2: Geocoding. The address is submitted to the Google Maps Geocoding API. If the API returns zero results and the input contains no postal code, the system does not reject the address outright. Instead, it asks the user to provide the postal code, a far more useful response than a generic error message. The user already knows their client's street name; they may simply have forgotten to include the code.

Stage 3: Normalisation confirmation. If the geocoded canonical form differs from the user's original input, the system presents both options and asks the user to confirm. This avoids silent normalisation that might introduce errors the user has no opportunity to review.

The Confirm-Different Flow

The confirmation dialogue is implemented as a WhatsApp interactive message with two buttons: one to accept the Google-normalised form, one to keep the original. The choice is stored in the typed session context, keyed to the specific pending invoice or onboarding step that triggered it. The geographic coordinates returned by the geocoder are stored alongside the address, enabling the customer map on the Kaepsi web dashboard.

Why This Matters

Address validation is often treated as a technical detail, a checkbox in the validation pipeline. We treat it as a conversation design problem. A user who receives "Adresse ungültig" and nothing more is frustrated and stuck. A user who receives "Habe 'Hauptstr.' gefunden, meinst du Hauptstraße 5, 60313 Frankfurt?" is informed and can proceed in ten seconds.

The quality of the error message is as important as the correctness of the validation. In a conversational interface, there is no tooltip, no inline hint, and no form label to provide context. Every system response is a message in a conversation, and it should read like one.