# How to read the address confirmation map

Every address answer says which dataset stood behind each part and what the parser changed. What each source means, and why unconfirmed is not wrong.

Date: 2026-09-16

Updated: 2026-09-24

An address answer used to tell you how far the building could be followed into a register and leave the rest to inference: if `match_level` was `street`, the street was fine and the number was not, and the postcode must have been all right or the address would have been invalid. That inference was usually correct and occasionally wrong, and it never said which dataset had done the work. Since 16 September 2026 every valid answer carries two fields that make it explicit: `confirmation`, a map from each part of the address to the source that stood behind it, and `changes`, the list of things the parser did to your input before anything was checked.

## The five parts and their sources

`confirmation` has exactly five keys — `postal_code`, `street`, `house_number`, `locality` and `administrative_area` — and each carries a source name, the word `unconfirmed`, or `null`.

| Source | Meaning |
| --- | --- |
| `postcode_directory` | The national postcode directory lists the postcode, or lists the town or region under it. |
| `postcode_area` | The town is not one the directory lists under the postcode itself, but it is one the directory lists somewhere in the postcode's area — or, where the postcode's region is a single city (Mexico City, Delhi, Jakarta, Bangkok, Moscow, Seoul and Tokyo's wards among them), it is that region's own name, such as Distrito Federal for 06000 or Tokyo for 100-0005. |
| `register` | A national address register followed the address at least this far: the postcode, the street, or the building itself. |
| `range` | The house number sits inside a range the register publishes for the street, without the building being listed. |
| `company_register` | An open company register lists companies at exactly this building, which proves the street and number exist. |
| `mail_drop_list` | A mailbox operator or a registered agent publishes this exact address as its own. |
| `pattern` | The postcode matched only the country's published shape; no directory or register was there to check it. A code the installed directory leaves out, such as a Northern Irish BT postcode, is never put to it, so an address in Belfast reads `pattern`, a box address or a street address alike: Open Names covers Great Britain only and is not asked about a BT code either. |
| `unconfirmed` | A dataset that could have confirmed this part did not. |
| `null` | Nothing on this server could check the part, or the part was not sent. |

Read the map top to bottom and it tells a story. A Swiss address that answers `postcode_directory, register, register, postcode_directory, null` was found in the postcode directory, followed to the building in the Swiss register, and has its town confirmed, while the region column is `null` because a Swiss address carries no region to check. A British address that answers `postcode_directory, register, unconfirmed, postcode_directory, null` had its street confirmed by Open Names, while its number was looked for only among the buildings Companies House lists companies at, and none was there: Britain's open street register lists no buildings.

## Why unconfirmed is not wrong

The word was chosen with care. `unconfirmed` says that a dataset in a position to confirm the part did not, and nothing more. Under a register that covers only part of its country — the United States National Address Database, the French Base Adresse Nationale, Britain's Open Names — a street that is not carried has not been called absent, because the register never claimed to carry every street. The verdicts live in other fields: `exists` for the building, which is `false` only under a register whose publisher claims complete coverage; `locality_matches_postcode` and `administrative_area_matches_postcode` for the town and the region. The map is the evidence beside those verdicts, and evidence of a check that could not settle the question is still evidence.

Two consequences follow. First, the risk signals are never derived from the map: `not_in_register`, `street_not_found` and `number_out_of_range` fire on the verdicts and on the register's own coverage claim, so an `unconfirmed` street under a partial register costs nothing. Second, a `null` is a fact about this server, not about the address — a country with no directory and no register installed answers `null` everywhere, and the honest reading is "not checked", never "not found".

## What the changes list says

`changes` records what the parser moved or set aside on the way from your input to the parts the datasets were asked about. It is empty for a cleanly separated address and carries one or more of these names otherwise:

- `country_line_removed` — the last line repeated the country ("United Kingdom", "USA", "Deutschland"); it was set aside so the town could be read from the line above it.
- `care_of_removed` — a line opening with c/o, attn, FAO, z.Hd. or their kin named an addressee rather than a place, and was dropped. The product is about places, so the name never reaches the answer.
- `building_separated` — a line without a number above the street carried a building word ("Rose Cottage", "The Old Rectory") and became `building`.
- `organization_separated` — a line without a number above a numbered street named a company or an addressee, and became `organization` because none was sent.
- `administrative_area_folded` — a state or province written in full was folded onto its code ("California" to CA).
- `box_line_moved` — a box line stood where the street line goes, and moved into `po_box` under the name the answer reports it by: Canada's `GD` reads `GENERAL DELIVERY`.
- `private_mailbox_moved_to_unit` — a PMB number on the street line became the `unit`. A bare `#` number is read as a flat or suite and becomes the `unit` without this change: `2261 Market St #4321` answers `address_type: street`.

What to do with them depends on where the address came from. From a form your own users filled in, `country_line_removed` and `care_of_removed` are worth feeding back into the form's design: a separate country field and an addressee field stop them recurring. From a file someone else exported, they are a record of what the pipeline judged, so a reviewer can see that "c/o Jane Smith" was read as a person and not as a street. `building_separated` is the one to act on: a building name is a real part of a British address and, if your own storage has no place for it, the `building` field is where the answer keeps it.

## An example, end to end

Sent as one line with the country set to GB:

```text
c/o Reception, Rose Cottage, High Street, Oxford, OX1 1AA, United Kingdom
```

The answer reads `building: "Rose Cottage"`, `street: "High Street"`, `locality: "Oxford"`, `changes: ["country_line_removed", "care_of_removed", "building_separated"]`, and — on a server with the British postcode directory and Open Names installed — a confirmation map of `postcode_directory` for the postcode, `register` for the street, `null` for the house number (there is none), `postcode_directory` or `postcode_area` for the town, and `null` for the region. Nothing in that answer had to be inferred, which is the whole point.

Reference: https://spaw.co/guides/how-to-read-the-address-confirmation-map