How to read the address confirmation map

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.

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:

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.