Ask anyone who has ever cleaned a customer database what the worst field is and they will say the same thing: the city. Not the email, not the phone number \u2014 the city, because it is the field people get wrong without ever realising they got it wrong.<\/p>\n
This is a long post about a small plugin. It covers why address entry fails, what the data actually looks like underneath, the three approaches we tried before settling on the fourth, and what it costs to do it properly. If you have ever exported a customer list and found “Springfeild”, this is for you.<\/p>\n
A typical checkout or quote form asks for street, city, state and ZIP. Four free-text fields, four opportunities for a typo, and no relationship between them enforced anywhere. What comes out the other side looks like this:<\/p>\n
Every one of those submits cleanly. No validation catches them, because each field is individually plausible. You find out weeks later when something is delivered to the wrong place or a tax return does not reconcile.<\/p>\n
The wrong address is only the beginning. Downstream, you get:<\/p>\n
The useful insight is that the ZIP code already contains everything else<\/strong>. Five digits determine, unambiguously, the city, the state, the county, the approximate coordinates and the timezone. If you have the ZIP, asking for the city is asking the user to re-enter information you already have \u2014 and giving them a chance to get it wrong.<\/p>\n There are roughly 41,000 US ZIP codes in active use. The full dataset with city, state, county, latitude, longitude and timezone is a few megabytes. That is small enough to sit in a database table on any host you are likely to be using.<\/p>\n It is not quite as clean as that paragraph implies, and this is where most implementations fall over:<\/p>\n The obvious answer, and the one we shipped first. It works beautifully until one of four things happens: the free tier runs out, the vendor rate-limits you mid-checkout, the vendor has an outage and takes your form down with it, or someone in legal asks why customer addresses are being sent to a company nobody has a contract with.<\/p>\n The latency is the quiet problem, though. A round trip to an external API is 100\u2013400ms. Fire that on every keystroke and the field feels laggy; fire it on blur and the user has already tabbed past.<\/p>\n A JSON file of every ZIP, loaded into memory. Simple, no dependencies \u2014 and a multi-megabyte parse on every request, which is exactly the kind of thing that makes people blame WordPress for being slow.<\/p>\n Let people type the city and suggest matches. This fixes spelling but not the relationship between fields \u2014 you can still pick Springfield, Ohio and then type an Illinois ZIP underneath it, and nothing objects.<\/p>\n An indexed database table, queried locally, triggered on the ZIP field.<\/p>\n The plugin creates one table at activation and imports the dataset once. The lookup is a single indexed query on a five-character primary key \u2014 sub-millisecond, on any host, every time. The ZIP field fires the lookup at five digits, and the city, state, county and timezone fields fill themselves in.<\/p>\n Where a ZIP has multiple acceptable city names, the official one is filled in and the alternates are offered in a dropdown rather than hidden. Where a ZIP crosses a county line, the primary county is returned and the alternate is exposed to code that cares. Nothing is guessed silently.<\/p>\n The genuinely fiddly part was never the data. It was that every form plugin names its fields differently, and half of them re-render the DOM after you have bound to it. The plugin binds by event delegation rather than direct listeners, so fields that appear after page load \u2014 conditional sections, repeatable groups, multi-step forms \u2014 behave the same as fields that were there from the start.<\/p>\n Field mapping is one filter:<\/p>\n The honest case for this is not that typing a city is hard. It is that:<\/p>\n Canadian postal codes are the most requested addition and are in progress. UK postcodes are harder \u2014 the data licensing is genuinely complicated \u2014 but they are on the list. Address-line autocomplete is not planned, because that genuinely does need a live service, and the entire point of this plugin is not needing one.<\/p>\n ZIP Autofill<\/strong> is in the catalog now. One-time price, local data, quarterly refreshes included.<\/p>\n","protected":false},"excerpt":{"rendered":" Why city, state and ZIP disagree with each other in every customer database, what the postal data actually looks like underneath, and the four approaches we tried before one of them worked.<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[68,1,62],"tags":[70,69,73,71,72],"class_list":["post-51","post","type-post","status-publish","format-standard","hentry","category-build-log","category-uncategorized","category-wordpress","tag-data-quality","tag-forms","tag-plugins","tag-ux","tag-zip-codes"],"_links":{"self":[{"href":"https:\/\/zyzxsolutions.com\/index.php?rest_route=\/wp\/v2\/posts\/51","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/zyzxsolutions.com\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/zyzxsolutions.com\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/zyzxsolutions.com\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/zyzxsolutions.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=51"}],"version-history":[{"count":0,"href":"https:\/\/zyzxsolutions.com\/index.php?rest_route=\/wp\/v2\/posts\/51\/revisions"}],"wp:attachment":[{"href":"https:\/\/zyzxsolutions.com\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=51"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/zyzxsolutions.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=51"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/zyzxsolutions.com\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=51"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}The awkward edges<\/h3>\n
\n
Three approaches that did not survive<\/h2>\n
1. Call a third-party API<\/h3>\n
2. Ship a flat file<\/h3>\n
3. Autocomplete the city instead<\/h3>\n
What we settled on<\/h2>\n
Working with forms that were not built for it<\/h3>\n
add_filter( 'zyzx_zip_field_map', function ( $map ) {\n $map['city'] = 'billing_city';\n $map['state'] = 'billing_state';\n $map['county'] = 'billing_county';\n $map['timezone'] = 'appointment_tz';\n return $map;\n} );<\/code><\/pre>\nWhat it is worth<\/h2>\n
\n
Where it is going<\/h2>\n