2026-09-16

Address intelligence round two: what a register knows about a building, and what the parser did to your input

The address answer grows from 45 to 53 fields: a confirmation map per part, a changes list, the building name, a region check, building use and units, coordinates from the registers, a street suggestion and a premise key. Postcode directories for a hundred countries, streets and towns for Great Britain, US address ranges, seven new national registers, registered agents, a streets endpoint, five test addresses, a fields option and three new weights.

The parser stopped losing four kinds of address. A last line that only repeats the country ("10 Downing Street, London, SW1A 2AA, United Kingdom", "…, CA 94043, USA", "…, 10115 Berlin, Germany") used to become the town, with the real town demoted to a dependent locality; it is now set aside, and when no country was sent and the line names exactly one, it becomes the country. A care-of or attention line ("c/o Jane Smith" above "221B Baker Street") used to become the street; it is dropped, because the product is about places. A building name above a numberless street ("Rose Cottage, High Street") used to become the street with the street demoted; it is now building, a new field that is also accepted as a separated input and as a list column headed building, building name, premise or house name. And a house-number range ("71-75 Shelton Street") used to fold to a number no register lists; it is now asked as written and then by either end, in the registers, the company register and the mailbox lists alike. Each of these moves is recorded in a new changes list — country_line_removed, care_of_removed, building_separated, organization_separated, administrative_area_folded, box_line_moved, private_mailbox_moved_to_unit — so the answer says what it did to your input.
53 fields, and a map of who confirmed what. Beside building: confirmation, an object naming for each of the postcode, the street, the house number, the town and the region which dataset stood behind it (postcode_directory, postcode_area, register, range, company_register, mail_drop_list, pattern), unconfirmed where a dataset could have and did not, or null where nothing could check; administrative_area_matches_postcode; premise_key, the hex digest of the building that every spelling of one address shares and that feedback and suppressions are filed under; building_use and is_multi_unit as the register declares them; street_suggestion; and changes. The guide at /guides/how-to-read-the-address-confirmation-map reads the map field by field; unconfirmed is never wrong.
Postcode directories for a hundred countries. The GeoNames postal-code dump, CC BY 4.0, installs one directory per country beside Britain's ONS directory: 105 countries and 1,097,486 codes from the 16 September copy, with the places each code is written with, the region and its code, and a centroid. Fifteen directories — the United States, Germany, France, Spain, Italy, Austria, Switzerland, Belgium, Denmark, Norway, Finland, Slovakia, Japan, Mexico and India — reach their operators' published totals and are recorded complete, so a code they lack answers postcode_not_found; the rest are partial and deny nothing. Canada, the Netherlands and Ireland publish only the forward sortation area, the four-digit district and the routing key, so those three match on their prefix and are partial whatever their size. Two consequences: administrative_area_matches_postcode compares the written state or province with the directory's, and a disagreement carries a new region_mismatch weight of 30; and locality_matches_postcode now checks the town against every place the directory lists for the code, then — before scoring anything — against every place in the postcode's area, so a post town written for a settlement reads confirmation.locality: postcode_area with no weight. The United States dump carries only each ZIP's default city, so an alternate city name there is reported as not matching and never scored.
Great Britain gets its streets and its towns. Ordnance Survey's Open Names, Open Government Licence, is installed as a register of streets keyed by postcode district: 999,065 road rows compile to 876,830 street keys in a 7.3-megabyte index, Welsh names indexed beside English ones. A British street the file lists answers match_level: street with confirmation.street: register; exists stays null because a register of streets lists no buildings, and a miss costs nothing because a road that runs through several districts is filed under one of them (87.3 percent of 49,106 Companies House street lines matched). The same file's postcode rows gave 1,742,466 of 1,749,109 installed British postcodes their places, so locality_matches_postcode answers in Great Britain for the first time, lenient to the region and the borough. The country page for GB says all of this in its own words.
A register now says where a building stands. The premise index keeps, beside every key, what the register publishes about the building: its position to about 1.2 metres, its use where the register categorises buildings, and its unit rows. A premise match answers latitude and longitude from the register with location_source: register, falling back to the postcode centroid as before; building_use reads residential, commercial, mixed, industrial, institutional, agricultural or other, and is_multi_unit is true at two or more listed units, false only where a register declares its units and lists none (the Austrian register counts dwellings), and null otherwise. National grids are converted in code — Swiss LV95, the Austrian Gauss-Krüger zones, Czech Křovák, Norwegian UTM 33 — and each conversion was checked against proj4js: the transverse Mercator and Helmert paths agree to between 0.02 and 0.06 metres, the Swiss approximate formula to between 0.4 and 2.3 metres. Recompiling the Swiss, Austrian, Czech and Norwegian registers grew each premise index from eight to fifteen bytes a key — the Swiss one from 25.8 to 48.1 megabytes — and the Federal Palace in Bern, the Storting and Oslo City Hall each answered within about twenty metres of their reference positions. A register compiled before this answers as it did until it is recompiled.
Seven more national registers, all open. Belgium's BeST address register in its three regional files (CC BY 4.0: Brussels 451,111 buildings, Wallonia 1,663,329, Flanders 2,798,435, every language spelling of a street indexed), Luxembourg's national addresses (CC0, 357,776 keys, filed under both spellings of the postcode), Latvia's State Address Register (CC BY 4.0, 322,198 buildings), Australia's G-NAF (CC BY 4.0 with its end-user clause against mailing lists; verified on the real tables, full compile pending), Denmark's national addresses (the agency's free geographic data; parser verified on fixtures, full compile not yet run) and, when a LINZ key is configured, New Zealand's street addresses (CC BY 4.0). Each names its licence in the answer's sources and its coverage claim in register_coverage. The Dutch BAG is not among them: its extract is a 3.6-gigabyte archive of archives that the reader cannot yet open, and it will come when it can.
United States address ranges. The Census Bureau's TIGER/Line address-range tables, public domain, compile into a range table consulted after the National Address Database has missed: a number inside a range published for its street answers a new match_level: range with confirmation.house_number: range and exists null, and a street the table knows whose number falls outside every range answers street with a new number_out_of_range weight of 20. A street the table does not know costs nothing, because the table is partial by measurement: not every edge carries a range and a street on a ZIP boundary can be filed under its neighbour. Delaware compiled in 23 seconds to 139,683 ranges on 24,424 streets; the national run is a few hours and about a gigabyte, started by hand.
Street suggestions, and a streets endpoint. Every register sync now keeps the streets it lists under each postcode by name. An address followed no further than its postcode answers street_suggestion, the register's spelling of the closest street (Banhofstrasse becomes Bahnhofstrasse, Limatquai becomes Limmatquai), and GET /api/v1/address/streets?country=CH&postal_code=8001 lists every street the register holds under a postcode — 200 in central Zürich — for one credit when it answers and nothing when it does not, with a seven-day repeat. GET /api/v1/address/postcode/{postcode} answers the same streets from the open registers wherever a listing is installed, at one credit, and keeps the licensed partner's full list for Great Britain and Ireland when one is configured.
Registered agents are named for what they are. A bundled list of registered-agent and formation services' own published offices — seventeen operators on 16 September, from the Delaware and Wyoming agents to the London formation addresses — answers mail_drop_source: registered_agent with the agent's name in mail_drop_provider, taking precedence over the company-cluster heuristic. The weight is the mail-drop 50, because nobody lives there; the guide says why a company registered there has done nothing unusual.
Three new weights, fourteen in all. region_mismatch 30, street_not_found 20 (a complete register of streets has no such street) and number_out_of_range 20 join the published table; locality_mismatch keeps its 30 but fires only when the town is found nowhere in the postcode's area and only where the directory lists every place a code is written with.
Five test addresses, a fields option, a ninth comparison. The houses numbered 1 to 5 on Spaw Test Street, Springfield, IL 99999 answer a valid address, a mail drop, an address a complete register lacks, a terminated postcode and — written "5 Spaw Test Street PMB 5" — a private mailbox, free, unlogged and recognised by every path including the sandbox key. fields on POST /api/v1/address and the browser endpoint keeps only the keys you name. And the cross-signal consistency check emits a ninth comparison, phone_address_region, the state a North American number was issued in against the address's region — evidence only, never a flag, because people keep their numbers when they move.
Deliberately not built. No cross-account address reputation, still: a postal address is where somebody lives, and a shared "post fails here" database would be a database about residences. No Dutch register yet, for the reason above. And no licensed delivery-point answers: is_deliverable, is_cmra, is_vacant and is_residential stay null until a partner is enabled, and building_use from a cadastre is never presented as the postal service's residential indicator.

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

All releases