2026-09-17

Address intelligence round three: the decision, the placeholders, the units, and what the parser did to your input

The address answer grows from 53 to 61 fields: ok_to_ship and blocked_by from a shipping policy you set once, looks_placeholder, unit_check, seen_by_you, the postcode as its operator prints it, the address as lines and in its own script. Three new weights, a parser corpus of 128 cases, directional and bis/ter folding, postcode directories that learn from the registers and from the Census, a bulk summary, British district pages, and registers for the Netherlands, three German Länder and Brazil.

One boolean per address, decided once. Every address answer now ends with ok_to_ship and blocked_by, decided by a shipping policy the account keeps: the signals that block whenever they fire, a ceiling on the risk score, and whether a national register must have confirmed the building. The order is fixed — an address that cannot stand as written first (blocked_by: invalid), then the first blocked signal in the published weights' order, then the score ceiling (risk_score), then the register requirement (unconfirmed) — and the defaults block undeliverable, placeholder and vacant and any score over 60, require no register, and leave a mail drop at 50 to pass, because whether a parcel may go to a mailbox shop is a merchant's call. GET, PUT and DELETE /api/v1/address/policy read, change and reset it, free and unlogged; the Shipping policy tab on the verification page edits the same three rules with checkboxes beside the weights; batch, bulk, monitored lists, the browser endpoint and the five test addresses all apply the account's policy, the guest demo the defaults. The guide at /guides/gate-a-checkout-with-the-shipping-policy suggests three policies and says why not_in_register deserves thought before it is blocked.
Placeholders are named for what they are. "asdf", "test", "n/a", "no address", "same as above", "123 Fake Street", a row of x's, a keyboard run, four letters with no vowel: looks_placeholder is true when the street or the town of a valid address is one of those, by WHOLE name only — "Test Valley Road" in Hampshire and "Sample Road" fold to keys the list does not carry and are never flagged, and a short real town like Rye or Ely is never judged. A true answer carries the placeholder signal at 60, cites the bundled address-placeholders list in sources, and is blocked by the default shipping policy. It is not a typo detector: a misspelt real street still answers street_suggestion.
A suite at a single-family home. unit_check reads the flat or suite you wrote against the units a register lists at the building it found: ok, missing (several units listed, none written, weight 20 as unit_missing) or unexpected (a flat or suite written at a building the register lists as a single residence, weight 30 as unit_unexpected), and null when the register did not find the building, does not say how many units it has, or lists one unit at a non-residential building, where a suite is ordinary. A private-mailbox number never counts as a unit, so a PMB is scored once. The Austrian register counts dwellings, the Belgian one carries box numbers and the Australian G-NAF lists flats as rows; the United States National Address Database fills its unit column on about fourteen percent of rows and therefore never calls a building single.
How often you have seen this address. seen_by_you counts your own account's lookups of the same address inside a seven-day window, with the first sighting — kept under the premise digest, never the address, and never anybody else's lookups. A free repeat still counts, the window closes from its first sighting, the guest demo and the test addresses answer null, and it carries no weight; what three lookups in a day should mean is a rule for your policy, not for the score. There is still no cross-account address reputation, and there will not be one.
The address as its operator prints it, as lines, and in its own script. postal_code_formatted writes the postcode the way its operator does — the British space, the Dutch space, the Canadian and Irish spaces, the Polish, Brazilian, Japanese and Portuguese hyphens, the ZIP+4 hyphen, the Luxembourg, Latvian, Lithuanian and Moldovan prefixes, plus Malta, Azerbaijan, Bermuda, Brunei, Somalia, Iran, the Cayman Islands, Lebanon and the American territories — and null when the postcode is missing or of the wrong shape. formatted_lines is the same rendering as formatted, one line per entry, for a label printer or a form with a field per line; a named building now stands on its own line above the street. formatted_local hands a Japanese, Chinese, Taiwanese, Hong Kong, Macao or Korean address written in Han, kana or Hangul back in that script and in the country's own largest-first order, 〒 kept, and stays null for a Latin-written one, because transliterating would be inventing characters the customer never typed.
Three new weights, seventeen in all. placeholder 60 joins private_mailbox at the top below undeliverable; unit_unexpected 30 sits with the 30s and unit_missing 20 with the 20s. The docs page, its twin and the product page carry the same seventeen rows in the same order, test-enforced.
A parser corpus, and what it found. 128 written addresses across 28 countries now run through the parser on every test run, each with the parts it must produce: the shapes fixed last round (country lines, care-of lines, building names, number ranges) and the ordinary ones. The first run disagreed on nine; five were parser gaps and are fixed — a spaced letter after a trailing number ("Musterstr. 12 a"), Singapore's "#20-01" unit written without a space, Korea's trailing house number, an Emirati office line in a country with no postcode and no town line, and a lone postcode-and-town line — beside the Italian province code after the town ("00100 Roma RM"). Twelve cases are recorded as known limits with today's answer and a note, capped at a fifth of the corpus, so the file documents rather than hides them: Irish counties, Turkish provinces, German, Danish and Spanish floor lines, French résidence and bâtiment lines, the Austrian door triple, Japanese block numbers, fractional American numbers, addresses written on one line with no separator, Indian states before the PIN, Russian house lines.
Directionals and repetition indices fold. "1201 W Peachtree St NE" now finds a register row filed as "West Peachtree Street", and the reverse, because every street is keyed under its variants — as written, without a leading directional, without a trailing one, without both — at query time and, from today, at compile time; "9 North Elm Street" finds "Elm Street". French "6 bis rue de la Paix" reads as number 6 bis, the way the Base Adresse Nationale files it, with ter, quater and quinquies alongside. One caveat: a register compiled before today answers the typed-side variants only until it is recompiled, which its next weekly sync does.
Postcode directories learn from the registers, and from the Census. Ten complete registers — Switzerland, Austria, Czechia, Norway, the three Belgian regions, Luxembourg, Australia and Latvia — now add, as they compile, every town they write under each postcode and a centroid to the country's directory, beside the directory's own rows and never in their place: a register of buildings never lists the box-only and large-recipient codes, so replacing the directory would have turned real box addresses into postcode_not_found. Coverage moves to complete only when an operator's published total is configured and the union reaches it, and none is configured yet. Measured on the Czech register: 38 codes added to the dump's 2,694 and 2,639 given the register's places. The United States, with no complete register, gets its extra place names from the Census Bureau's ZCTA-to-place file, public domain: 28,668 of 41,488 ZIPs gained places in 3.5 seconds, 94043 now lists Mountain View, Palo Alto and Sunnyvale, and "1 Main Street, Palo Alto, CA 94043" answers a matching town. It does not list Moffett Field or Hollywood — the file describes the places whose land a ZIP touches, not the names the postal service accepts — so an American town mismatch is still reported and still never scored.
A summary on every finished bulk run. The address bulk payload now carries summary, built from the same cells the CSV holds: rows and duplicates, valid and invalid with their reasons, the risk split, the top ten countries and mail-drop operators, the address types, how far each row was followed into a register, how many rows carried each of the seventeen signals, the placeholders, and blocked — the rows the shipping policy refused. The dashboard's bulk panel shows it under each run; the webhook body is unchanged.
A page for every British postcode district. Each of the 2,872 outward codes with data behind it — 2,752 of them indexable — has a page under the address checker at /tools/address-checker/gb/districts: the postcode area and its name, the places Open Names lists for the district's postcodes, the live and terminated postcode counts, the streets filed under the district with the first twenty, a centroid, the datasets and their versions with the Open Government Licence attribution, and a hand-off into the checker with the district prefilled. SW1A lists 145 live postcodes and 33 streets; RG5, 504 and 285. A page says whether codes are in use, never who is there; a road is filed under one district; and there is no open register of buildings in Britain, so exists stays null there. Northern Ireland has no pages, because BT postcodes need a licence the open directory does not carry.
The round-trip report stopped failing on what it cannot measure. The weekly self-check that sends each register's own rows back through the pipeline now lists a register it cannot run under unmeasured with the reason — the British register of streets is keyed by district, whose rows the lookup refuses as a postcode before any match; the TIGER range table is managed by its own command and has no raw file to sample — instead of scoring them nought and failing every Saturday.
More registers. Germany gets its first open registers, a Land at a time, from the three Länder that publish house coordinates a fetcher can read: Berlin (Datenlizenz Deutschland Zero 2.0, 402,523 buildings), North Rhine-Westphalia (Datenlizenz Deutschland Zero 2.0, 4,503,290 buildings, keyed by municipality because the file carries no postcode) and Rhineland-Palatinate (Datenlizenz Deutschland Namensnennung 2.0, 1,404,472 buildings), all compiled on 17 September and round-tripping at 100 percent; each is partial, because a Land is not the country, so a German address the installed Länder do not carry answers exists: null, never false, and the other Länder either sell their data or publish nothing a fetcher can read. Brazil gets the IBGE's 2022 census address list, CNEFE, as twenty-seven state registers under one dataset — free public data with attribution to IBGE, partial because it is a 2022 snapshot — with a position, a building use and a unit from the complement fields for every point; verified on Roraima, 135,417 buildings at 100 percent, and the national compile is about 226 million rows and two and three-quarter hours. To read it, Portuguese street types and titles now fold onto one spelling, so RUA and R, AVENIDA and AV, SANTA and STA agree on both sides of a match. And the Dutch BAG, CC0 and complete, is in the register list: the parser reads the 3.6-gigabyte archive of archives through a new nested-archive reader, verified on a fixture built to the extract's shape, with the compile of the real file under way as this entry is written. Each register names its licence in the answer's sources and its coverage claim in register_coverage.
Deliberately not built. An American town mismatch still carries no weight, for the reason above. A register compiled before today answers only the typed-side directional variants until it is recompiled. The unit check counts a register's units and never matches them, because "Apt 7", "7", "Wohnung 7" and "bus 7" rarely agree across a register and a customer. And there is still no cross-account address reputation: seen_by_you is your own account's traffic and nobody else's.

markdown version: /changelog/2026-09-17-address-intelligence-round-three.md · atom feed: /changelog.atom

All releases