Address Splitter

How a split gets checked at all

Here is what two of the common address parsers do with a Paris address. Both are popular, both are used in production, and neither reports a problem.

45 Rue de Rivoli, 75001 Paris, France

parse-address  →  { number: "45", street: "Rue" }
addresser      →  threw an exception whose message was "undefined"

Five of the seven words are gone. Not misplaced, not flagged, gone. The result is an object with two fields filled in and no record anywhere of what the input contained, so nothing in it can tell you that anything is missing. Feed it an Irish address and eight of the nine words disappear the same way.

That is the failure this category is built on, and it is a counting problem.

So the rule here is one sentence long. Every word that went in has to come out in exactly one column. Nothing may vanish, nothing may appear twice, and nothing may turn up that you never typed. Each word of the address carries an index through the parse, and at the end the columns are counted back against the input.

It is a cheap check and it catches a lot. A street name the parser could not finish reading leaves words behind, and those words get named. A country that fell off the end gets named. A line that was never an address at all fails the count so comprehensively that the page can say so instead of inventing a street called "just".

What counting cannot catch is a word that landed in the wrong column, because the total still comes out right. So the shapes are checked too. A postcode is tested against the written form for the country it was read as, a state against that country's actual list, and a street that begins with a single stray letter gets flagged, because that is almost always a house number like 221B that was split in two.

None of this needs a server, and we would rather it did not have one. A list of addresses is a list of where people live, so the file is read by code already sitting in this tab and the spreadsheet is written here too. You can watch your browser's Network tab while you use it, or pull the plug on your connection after the page has loaded and carry on working offline. We built it this way because the free tools in this category are front ends to a paid API, which is also why they all stop at five hundred rows.

What is not claimed. No accuracy percentage. Every competitor in this category publishes one, none of them say what it was measured on, and a number like that tells you nothing about your own list. What is claimed is narrower and checkable: nothing gets dropped in silence. When the tool is unsure, the row says so and says why.

Why reading left to right is the mistake

The left hand end of an address is its least reliable part. A street name can be one word or six, in any language, with the type word at the front in French and glued onto the back in German. There is nothing dependable to anchor to.

The right hand end is the opposite. A country name is a closed list. A postcode has a shape, and often a very distinctive one. A state code is two letters drawn from a list of fifty. Those three can be found with near certainty wherever they happen to sit in the line.

So this works inwards from the end: find the country, find the postcode, find the state, find the unit and the box, and only then decide what the words in the middle are. By the time the uncertain part is reached it is bounded on both sides, and the guessing has somewhere to stop.

A hundred and thirty six countries, and the one thing that changes between them

Most of Europe writes the house number after the street. The English speaking world writes it before. That single difference is why a German address turns inside out in a tool built for American ones, and it is not a rare edge case: it is most of the continent.

Postcodes vary more than people expect too. Britain writes letters and digits in six different arrangements. Canada alternates letter and digit. The Netherlands puts two letters after four digits. Poland uses a hyphen, Portugal uses a different hyphen in a different place, and the Emirates have no postcodes at all, so a parser hunting for one there finds a phone number.

Each country's postcode has two patterns here rather than one, and the reason is worth saying plainly. A loose pattern is used to find the postcode in the line; a strict one decides whether what was found is well formed. Searching with the strict pattern is the mistake: a postcode with a typo in it then matches nothing, so it is never found, so it drifts into the city column or falls off the row, and nobody is told. Found loosely and checked strictly, the same typo lands in the right column wearing a flag.

One detail of this took three attempts to get right, and it is a good illustration of the whole problem.

A five digit postcode cannot tell you the country. It is France, Germany, Spain, Italy, Finland, Mexico and a United States ZIP code, all at once. The United States was left off that list of ambiguous cases at first, so it won every tie, and "45 Rue de Rivoli, 75001 Paris" came back as an American address with "de" filed as the state of Delaware. The fix was partly to stop treating a ZIP code as more distinctive than anyone else's postcode, and partly to notice that a lowercase two letter word in the middle of a street name is a particle, not a state.

Where the rules run out. A hundred and thirty six countries have their own postcode shapes and number conventions here. Beyond those, an address still splits on general rules and the page says plainly that it could not identify a country, rather than quietly applying American ones. If two countries fit equally well, neither is named, but the split still goes ahead on whatever the two agree about. Spain and Mexico cannot be told apart by a Madrid address and they do not need to be: both write the number after the street, so the columns come out right either way and only the label is unknown.

The file checked against itself

Counting the words of one address can only tell you about that address. A file of them carries something a single row does not, which is repetition.

The same postcode turns up in forty rows, and in thirty nine of them the city is spelled Birmingham. That makes the file its own reference data. Nothing is downloaded and nothing is looked up on a server: the majority spelling is evidence about the odd one out, and the odd one out is nearly always a typo in whatever system the list came from that nobody has ever noticed.

It is the only check here that can find a mistake in an address that split perfectly.

Digits are not all written with the same shapes

A house number in Cairo is written ١٢٣. A postcode in Bangkok is ๑๐๑๑๐. Those are numbers, and everything that recognises a number is written in the ten shapes English uses, so to a parser they are just unfamiliar letters.

Twenty one digit systems are read here: Arabic-Indic and the extended set used in Iran and Pakistan, Devanagari, Bengali, Gurmukhi, Gujarati, Tamil, Telugu, Kannada, Malayalam, Sinhala, Thai, Lao, Tibetan, Myanmar, Khmer, Mongolian, Odia, Javanese, N'Ko, and the full width digits Japanese documents use.

Each word carries a shadow of itself with the digits mapped across, and the patterns are matched against the shadow. What comes out keeps the digits you wrote. Nobody in Cairo wants their addresses handed back renumbered.

The script itself turns out to be useful evidence too, and sometimes the only evidence there is. A Greek address with no country word in it was coming back as a tie between seven countries that all write five digit postcodes. The alphabet settles it.

Addresses with no spaces in them

A Chinese address is frequently written straight through with nothing between the parts:

北京市朝阳区建国路93号 100022

There is no word boundary anywhere in that, so a tokenizer has nothing to work with and every parser we tried either refused the line or dropped the whole thing into one column. It also runs the opposite way round from a Western address, largest division first.

What makes it tractable is that each division names itself. The character 市 closes a city, 区 closes a district, 路 closes a road, 号 closes a house number. The words are unknown and stay unknown, but the boundaries are marked, and boundaries are all a splitter actually needs. The same holds for Japanese and Korean, each with their own markers.

One of those markers caused a bug worth repeating. The character 道 ends a Japanese prefecture, in 北海道, and also means boulevard in Chinese, in 世纪大道. Run as a single list of markers, the Japanese prefecture rule swallowed a Shanghai street and filed it under province. The rules are kept per script now, which is the only way that stays fixed.

Honestly, what this does not do. An address written in the standard order comes out in columns. One written some other way comes back flagged, with the part that matched no marker shown to you, rather than guessed at. There is no language model here and no dictionary of place names: it is a closed set of suffix characters, which is why it fits in a page of code and runs offline.

What a second look found

Everything above passed before this part was written. That is the awkward bit. A test suite only proves the cases somebody thought of, so once it was finished we went back and attacked it: addresses it had never been shown, output read in the downloaded file rather than on the screen, and every test deliberately broken to see whether it actually failed.

Several things fell out. None of them had been complaining.

How the tests were tested. Thirty six deliberate faults were introduced into the working code, one at a time, to check that something failed. Nine of them passed, which meant nine tests were not doing anything at all. Each was rewritten, and the rewritten ones immediately found four more faults in the parser, including two whole scripts that were not being read properly. One of the nine turned out to be guarding nothing: the rule it protected was already enforced elsewhere, so the dead constant was deleted rather than given a test to keep it alive. A test that has never failed is not a test.

What has actually been tested

Every figure here is a test run that has to pass before anything reaches this page. If one fails, nothing ships. They run in about three minutes and they have run on every change.

• 460The parser, the exports, the file check and every file that ships run-tests
• 47665 languages with a real address each, and rubbish written in 22 of them languages
• 448All 136 countries, 34 digit systems and the scripts with no spaces world
• 328Layout, tap targets and enlarged browser text at twelve screen sizes responsive
• 314Input nobody would type, including rubbish in eleven scripts adversarial
• 196What the page looks like at seven sizes, down to whether every control is styled visual
• 61The writing on this page, checked for the tells of generated copy humanize
• 59Broken encodings, lines too long for a carrier, addresses the post cannot use fitness
• 45The live page in a real browser, under the security policy it ships with e2e
• 39A mixed file coming apart into one usable file per country groups
• 33Every icon and image is the real brand asset, not a placeholder brand
• 17Fifty thousand rows, in batches, with the cost per row held flat scale

Two things we deliberately do not publish. There is no accuracy percentage here. Every competitor in this category prints one and none of them say what it was measured on, and a number from somebody else's list tells you nothing about yours. What is published instead is the verification: 2,476 checks, named, with the rule each one enforces. And the test browser is Chromium, which is the engine behind Chrome and Edge; the page uses nothing that Safari or Firefox lack and has been looked at in both, which we would rather say plainly than imply a number we did not measure.

What this will not do

Worth knowing before you drop a file in, because two of these come up often.

Common questions