Know what kind of address you were given.
One POST request reads a postal address the way its own country writes it, names the delivery point behind it — a street, a post-office box, a private mailbox at a mail-receiving agency, a parcel locker — checks the postcode against the national directory, follows the building into the country’s own address register, and counts the companies registered there.
Free credits every month. No credit card required. The demo on this page runs against the live service.
Live demo
POST /demo/address · no key needed
Response
Look up any address to see the full API response, straight from the live service. The country decides which format it is read against.
Every response field, documented.
This is the actual contract of POST /api/v1/address — 61 fields in a fixed order, then sources naming the datasets actually consulted with the version of each, and meta with your credit usage. Signals are tri-state: false is a checked negative, null means the dataset behind it is not installed and nothing was evaluated.
| Field | Type | Example | What it tells you |
|---|---|---|---|
| valid | Whether the address stands as written for its own country: every part that country’s format requires is present, the postcode has the right shape, and — where a national directory is installed — that postcode exists. | ||
| reason | Why it does not: empty_address, missing_country, unknown_country, missing_street, missing_locality, missing_administrative_area, missing_postal_code, invalid_postal_code or postcode_not_found. Invalid addresses are free. | ||
| country / country_name / continent | The ISO 3166-1 alpha-2 code you sent, its English name, and the continent code. | ||
| is_eu / is_eea / privacy_regime | EU and EEA membership, and the comprehensive privacy law that applies where the address is — the same country facts the phone and IP lookups answer, so one code path can set defaults from any of them. | ||
| formatted | The address written the way that country’s postal operator writes it: its own line order, its own uppercasing, and the parts that are missing left out rather than blanked. | ||
| formatted_lines | The same rendering as formatted, one line per array entry, for a label printer or a form with one field per line. Null when formatted is. | ||
| formatted_local | The address in the country’s own script and line order where the format table carries one (Japan, China, Korea, Taiwan) and the input was written in that script. Null otherwise. | ||
| organization | The company line, when one was sent or recognised in the written address — a line without a number above a numbered street reads as the organisation. | ||
| building | A building named instead of numbered, sent as its own field or separated from the street line of a written address by the parser. | ||
| street / house_number | The street name and the number, split apart and put on the side of the name that country writes it — leading in the United States, trailing in Germany. | ||
| unit | The flat, suite, floor or mailbox line, including a private-mailbox number lifted out of the street line. A floor written before or after the street is read as the unit, and several units are kept, joined with ", " in the order written: 5th Floor, Suite 500. | ||
| po_box | The box line as the operator writes it, in that country’s own words. A box written where the street goes moves here and clears the street; a box on a line of its own beside a street keeps both. | ||
| dependent_locality / locality / administrative_area | The district, the town or city, and the state, province or county — folded to its code where the country writes one. | ||
| postal_code / postal_code_formatted / postal_code_valid / postal_code_type | The postcode, whether it matches that country’s pattern, and what the country calls it: zip, eircode, pin or postal_code. All three are null in the countries that use no postcodes. postal_code_formatted is the same postcode written the way its operator prints it — the British space, the Polish hyphen, the ZIP+4 hyphen — or null when it is missing or of the wrong shape. | ||
| postcode_status | live or terminated, from the national postcode directory. A terminated postcode is a real address that has moved on, not a typo. Null where no directory is installed, where the directory does not list the code, and for a code outside its scope — in Great Britain a Northern Irish BT postcode, a BFPO number, a BF1 or a BX code — which is never refused. A ZIP+4 is looked up by its ZIP. | ||
| locality_matches_postcode / administrative_area_matches_postcode | Whether the town, and the state or region, written on the address are the ones the directory publishes for that postcode. Null when either side is unknown, and for an Irish county inside the province an Eircode routing key is filed under, except that County Dublin is confirmed for a Dublin district key other than D11 and D15, and a Leinster county is refused for P14, which GeoNames files under Leinster though none of its sales is there. A town the directory lists elsewhere in the postcode’s area, a single-city region’s own name (Distrito Federal for 06000, Tokyo for 100-0005), or a town a default-city-only directory does not carry reads false without a weight — confirmation says which. | ||
| address_type / address_type_source | What kind of delivery point the address names — the nine values below — and what said so. The source is address_rules when the operator’s own naming settled it. | ||
| is_po_box / is_private_mailbox | The two types worth branching on directly. is_po_box is null in a country whose box naming we do not carry; is_private_mailbox is true when the address is written the way the postal service requires a mail-receiving agency to be written. | ||
| exists | True only when the building itself was found in the country’s official address register. False only when a register whose coverage is complete does not carry it. Null otherwise — including under a register whose coverage is partial. | ||
| match_level | How far the address could be followed into that register: premise, range, street, postcode or none. Null when no register covers the country. | ||
| register / register_coverage | Which register answered and how complete it is: complete or partial, as its publisher says, except where Spaw marks a register partial because its copy cannot vouch for an address it lacks — the address data sources page says which. Read exists against this, always. | ||
| premise_key | A digest of the building — the same key your outcome reports and suppression list are filed under, shared by every spelling of one address, so it is what to join and deduplicate on. A key of a place, never of a person. | ||
| building_use / is_multi_unit / unit_check | What the register that found the building says it is used for, and whether it lists several flats or suites there. Only what a register declares — never inferred, null where it publishes neither. unit_check reads the unit you wrote against those units: ok, missing (several units listed, none written) or unexpected (a flat or suite at a single residence); null when the register cannot say. | ||
| street_suggestion | The street the register most likely meant when the one typed is not in the postcode but one close to it is, in the register’s own spelling. | ||
| latitude / longitude / location_source | Where the building stands when the register that found it publishes a position, about a metre of precision; otherwise the postcode centroid, and the field says which of the two it is. | ||
| companies_registered | How many companies still on an open company register name this address. Null where no register covers the country. | ||
| is_mail_drop / mail_drop_provider / mail_drop_source | Whether the address is one mail is received at on other people’s behalf, who publishes it when an operator or a registered-agent service does, and which of the three sources answered: operator_list, company_cluster or registered_agent. | ||
| deliverability_checked | Whether the licensed deliverability check ran. False whenever the lookup did not ask for it with deliverability: true, and until a partner is configured. | ||
| is_deliverable / is_cmra / is_vacant / is_residential | What that check said: whether post is actually delivered there, whether the postal service records the delivery point as an agency, vacant, or residential. Null until it runs — never a guess in its place. | ||
| confirmation | What stood behind each part — the postcode, the street, the house number, the town, the region — named by the dataset that confirmed it, unconfirmed when a dataset that could have did not, null when nothing could check it. | ||
| changes | What the parser moved or set aside on the way from your input to these parts — a country line, a care-of line, a building name, a state folded to its code — so a normalisation is never silent. | ||
| looks_placeholder | Whether the street or the town is what somebody types to get past a form rather than a place: a test word, a keyboard run, a refusal, a name with no vowel. Whole names only — a real street that merely contains one of the words is never flagged. | ||
| seen_by_you | How many times your own account looked this address up inside the window before this call, and when the first of those was — kept under the premise digest, never the address, and never anybody else’s lookups. | ||
| risk_score / risk_level | The sum of the weights below, capped at 100; high from 60, medium from 30. Null for an invalid address. | ||
| risk_signals | Every signal that contributed, with the weight applied and the dataset behind it, so the weights always sum to risk_score. | ||
| ok_to_ship | Your account’s shipping policy applied to this answer: false when a blocked signal fired, the score is above your ceiling, the register did not confirm a building you require confirmed, or the address cannot stand as written. | ||
| blocked_by | What decided a false ok_to_ship: invalid, the first blocked signal in the weights’ order, risk_score, or unconfirmed. Null when shipping is fine. |
One request, written on one line or split into fields.
- Send one written address, or the separated fields, always with a country
- Fields sent beside a written address win over what the parser read out of it
- Lookups run against local data — no upstream API in the request path
- Batches of 100 per call, queued bulk runs of 100,000, and a browser endpoint for publishable keys
- Invalid addresses answer a typed reason, free of charge
- Repeats of a charged lookup are free for seven days, however they are spelled
Where it runs: Google Sheets as =SPAW_ADDRESS; Zapier, Make and n8n through their own HTTP steps today, with Spaw’s apps for them built and not yet listed; the Node.js, Python and PHP clients, built and awaiting publication; and a Shopify recipe that checks each order’s shipping address after checkout through Zapier or Make.
$ curl https://spaw.co/api/v1/address \ -H "Authorization: Bearer sk_live_…" \ -H "Content-Type: application/json" \ -d '{"address": "2261 Market St PMB 4321, San Francisco, CA 94114", "country": "US"}' { "success": true, "data": { "valid": true, "reason": null, "country": "US", "privacy_regime": "ccpa", "street": "Market St", "house_number": "2261", "unit": "PMB 4321", "locality": "San Francisco", "administrative_area": "CA", "postal_code": "94114", "postal_code_valid": true, "postal_code_type": "zip", "address_type": "private_mailbox", "address_type_source": "address_rules", "is_private_mailbox": true, "exists": null, "match_level": "street", "register_coverage": "partial", "is_mail_drop": false, "deliverability_checked": false, "is_deliverable": null, "confirmation": { "postal_code": "postcode_directory", "street": "register", … }, "changes": ["private_mailbox_moved_to_unit"], "looks_placeholder": false, "risk_score": 60, "risk_level": "high", "risk_signals": [{ "signal": "private_mailbox", "weight": 60, … }], "ok_to_ship": true, "blocked_by": null, "sources": [{ "dataset": "address-rules", … }, …], … }, "meta": { "credits_used": 1, "credits_remaining": 499, "cache_hit": false } }
Address types: not every address is a place.
Half of what an address tells you is what kind of delivery point it names, and postal operators say so in their own words. Those words — 52 operators’ worth — are what address_type reads.
| address_type | What it means |
|---|---|
| street | An ordinary street delivery point: a place, where somebody can be visited or served. |
| po_box | A post-office box, in that operator’s own words — PO Box, Postfach, Boîte Postale, Casella Postale, Skr. poczt., 私書箱. |
| private_mailbox | A box rented at a mail-receiving agency, written the way the postal service requires: a PMB number after a real street address, or a PostNet Suite in South Africa. |
| general_delivery | Held at the counter for collection: General Delivery, Poste Restante, Postlagernd. |
| rural_route | A rural route or highway contract route rather than a numbered street address: RR, HC, RFD. |
| military | Military and diplomatic mail: APO, FPO, DPO, PSC, CMR, BFPO, CFPO. The address is a routing instruction, not a place. |
| parcel_locker | An automated parcel machine or collection point, written the operator’s way: Deutsche Post’s Packstation in Germany, Australia Post’s Parcel Locker and Parcel Collect in Australia. |
| bulk_mail | A business-volume arrangement: the French CEDEX, TSA and CS, the Dutch Antwoordnummer. A CS or TSA line replaces the street, as a box does; CEDEX is written after the town, so the street stays. |
| unknown | We carry no box naming for that country, so nothing was classified. Not the same answer as street. |
A risk score whose arithmetic you can repeat.
Every weight is published here and repeated in risk_signals with the dataset that produced it, so the sum can be recomputed from the same response — or ignored entirely in favour of the flags. 60 and above is high, 30 and above medium, capped at 100. An invalid address has no score at all.
It measures how unlikely an address is to be somebody’s own front door, not fraud. A box is not scored in the countries where a box is how post normally arrives.
One weight comes from you: report what happened to the post you sent — delivered, returned, moved or refused — and your own later lookups of that address carry it. Those reports are never shared with another account and never will be. An IP address is a network endpoint and a phone number is a handset, but a postal address is where somebody lives, and a shared “post fails here” database would be a database about residences.
| The deliverability partner says post is not delivered there | +80 |
| A private mailbox at a mail-receiving agency | +60 |
| A street or town typed to get past the form: a test word, a keyboard run, a refusal | +60 |
| A mail drop: an operator’s published branch, or more companies registered than the threshold | +50 |
| Your own most recent outcome report for the address was returned, moved or refused | +50 |
| The deliverability partner records the delivery point as vacant | +40 |
| General delivery, held at the counter | +40 |
| A post-office box, where a box is not the ordinary way to receive mail | +30 |
| A flat or suite written at a building the register lists as a single residence | +30 |
| A postcode the directory has terminated | +30 |
| The town does not match the one the directory publishes for the postcode, nor any place in its area | +30 |
| The region does not match the one the directory publishes for the postcode | +30 |
| Not in a register whose coverage is complete, so exists is false | +20 |
| No flat or suite written at a building the register lists several units at | +20 |
| The street is not in a register of streets whose coverage is complete | +20 |
| The house number falls outside every range published for a known street | +20 |
| A business-volume arrangement such as a CEDEX | +20 |
Open data, named and licensed.
Every dataset behind an answer is public, licensed for commercial use, and named in the sources block with the version installed when the answer was given. The licences that ask for attribution get it in the footer of every page.
Where the table names an address register for a country and it is installed, match_level is answered from it, and so is exists where the register lists buildings — Great Britain’s lists streets, so exists stays null there; everywhere else both answer null. The free address checker publishes the same thing country by country — how the country writes an address, its operator’s box words, and which register, postcode directory and company register this server holds there — for the United States, France, Germany, Switzerland and every other country it indexes. Great Britain’s register lists streets rather than buildings, so each of its postcode districts has a page of its own, with the streets Ordnance Survey files under it.
| Dataset | Covers | Refreshed | Licence |
|---|---|---|---|
| address-formats | What an address needs in 207 countries and territories: the line layout, the required fields, the postcode pattern, and what that country calls its postcode, locality and administrative area. | ||
| address-rules | How 52 postal operators name a delivery point that is not a street: boxes, private mailboxes, general delivery, rural routes, military mail, parcel lockers and business-volume arrangements, plus the words that look like a box but mean a flat. | ||
| us-national-address-database | Street addresses across the United States with their positions and, where filled in, their use, as the states and local authorities that take part share them with the Department of Transportation. Coverage is partial, and the response says so. | ||
| us-tiger-address-ranges | The house-number ranges the Census Bureau publishes for every road edge and its ZIP, so a number can be placed on a street no building register carries. Partial by nature; a street it does not know is never denied. | ||
| fr-base-adresse-nationale | Addresses and their positions in France and its overseas regions, from the Base Adresse Nationale (IGN/DINUM). | ||
| os-open-names | Every named and numbered road in Great Britain by postcode district, and the places every postcode is written with. Streets, never buildings. | ||
| ch-gebaeudeadressverzeichnis | The official directory of building addresses for Switzerland, with positions and building categories. | ||
| at-adressregister | Austria’s address register, from the Bundesamt für Eich- und Vermessungswesen, with positions, building use and dwelling counts. | ||
| cz-ruian-adresni-mista | Czechia’s RÚIAN address points and their positions, from the Czech Office for Surveying, Mapping and Cadastre. | ||
| no-matrikkelen-adresse | Norway’s addresses and their positions from Matrikkelen, the national property register kept by Kartverket. | ||
| be-best-address (Flanders, Wallonia, Brussels) | Belgium’s three regional address registers, republished daily by the federal BeST service, with positions and box numbers; every language spelling of a street is indexed. | ||
| lu-bd-adresses | Luxembourg’s national address file and its positions, from the cadastre. | ||
| au-gnaf | Australia’s Geocoded National Address File, with positions and flat numbers. The licence forbids building a mailing list from it, and nothing here does. | ||
| lv-valsts-adresu-registrs | Latvia’s State Address Register and its positions. | ||
| dk-danmarks-adresser | Danmarks Adresseregister, with positions, floors and doors, from a copy taken on 26 September 2026: the interface it was read through closed on 1 October 2026. Coverage is partial until the register is read from its new distribution, so an address that is not found reads as unknown, not absent. | ||
| nz-linz-addresses | New Zealand’s street addresses and their positions from LINZ, on servers configured with a LINZ Data Service key. | ||
| ons-postcode-directory | Every Great Britain postcode with its status, the dates it was introduced and terminated, its centroid and its local authority. Northern Ireland postcodes are excluded: reusing them needs a separate Land & Property Services licence. | ||
| geonames-postal-codes | Postcodes outside Great Britain in about a hundred countries, with every place listed under a code, the region and a centroid. Complete in fifteen countries, partial elsewhere, and the response says which. | ||
| geonames-cities | The other names a town or a one-city region is written under — Munich for München, Moscow for Москва — for the town and region checks: places of 15,000 people or more, compared inside one country, and a town only within 30 km of the place. | ||
| ie-property-price-register | Which counties the Irish Eircode routing keys that reach into another province cover, and that D11 and D15 reach into Meath, derived from the register’s residential sales. Only that table ships; no sale, address or price is held. | ||
| uk-companies-house | The registered office of every UK company, from the free company data product, counted per address; a dissolved company has already left the file. | ||
| fr-sirene-establishments | The address of every active establishment in INSEE’s Sirene base, counted per address; an establishment whose owner has opposed publication has no address in the file and is not counted. | ||
| no-enhetsregisteret | The business address of every entity in the Brønnøysund register, counted per address. | ||
| company-registers (US) | Principal and registered-agent addresses from the Colorado, New York, Oregon, Connecticut and Hawaii business registries, counted the same way; a dissolved, withdrawn, revoked or merged entity is not counted. | ||
| mail-drop-locations | The branch addresses mailbox and mail-forwarding operators publish themselves — The UPS Store, PostNet, PostScan Mail, Opus and Davinci in North America, Mail Boxes Etc in the UK and Ireland — so a match can name the operator. | ||
| registered-agents | The addresses of registered-agent and formation services in the United States and the United Kingdom — each one an address the agent publishes as its own, or one that a public listing or filing naming the service carries — so a cluster of companies there is named for what it is. | ||
| nl-bag-adressen | exists and match_level in the Netherlands, from the Basisregistratie Adressen en Gebouwen kept by Kadaster. Coverage is complete. | ||
| br-cnefe-2022 | exists, match_level and the building’s position in Brazil, from IBGE’s Cadastro Nacional de Endereços para Fins Estatísticos, the 2022 census address list, one file per state. Coverage is partial: a census list, not a live register. | ||
| de-berlin-adressen | Berlin’s address register from Geoportal Berlin, postcode included: exists, match_level and the building’s position in one Land. | ||
| de-nrw-gebaeudereferenzen | North Rhine-Westphalia’s building references from Geobasis NRW, filed by municipality because the open product carries no postcode. | ||
| de-rlp-hauskoordinaten | Rhineland-Palatinate’s house coordinates from LVermGeoRP, filed by municipality because the open product carries no postcode. | ||
| register-derived postcodes | The postcodes a complete register of buildings lists, added to the country’s directory where the directory lacks them, with the register’s places and centroids beside the directory’s own — never replacing it, because box-only codes a register of buildings never lists must keep answering. | ||
| address-placeholders | looks_placeholder: the words and shapes people type instead of an address, matched as whole names only. |
Data synced on 2026-10-17: the newest register, postcode directory, company address or mail-drop install behind the answers on this page. Every response carries the same dates in its sources block.
The weekly round trip
Every Saturday we take rows straight out of each installed register’s own file and send them back through the ordinary lookup. It checks our plumbing, not a country: the file is compiled by one code path and queried by another, so a parser that spells a street one way and an index that folds it another would answer nothing for a whole country, silently and with no error. A share near 100% means the round trip holds. It is not a measure of how many of a country’s addresses the register carries, and we do not have one. The countries column is the scope the register declares, not a sampling frame: the rows come from the register’s own file, however many countries it declares. A register published in several files, like Brazil’s one per state, is one row with every file’s sample added up. The version is the publisher’s, the oldest file’s where there are several. Last run 2026-10-17.
| Register | Countries declared | Register version | Declared coverage | Rows found again |
|---|---|---|---|---|
| us-national-address-database | US | 1,999 of 2,000 (100%) | ||
| fr-base-adresse-nationale | FR GP MQ GF RE YT PM BL MF | 2,000 of 2,000 (100%) | ||
| ch-gebaeudeadressverzeichnis | CH | 2,000 of 2,000 (100%) | ||
| at-adressregister | AT | 2,000 of 2,000 (100%) | ||
| cz-ruian-adresni-mista | CZ | 2,000 of 2,000 (100%) | ||
| no-matrikkelen-adresse | NO | 2,000 of 2,000 (100%) | ||
| be-best-address-flanders | BE | 2,000 of 2,000 (100%) | ||
| be-best-address-wallonia | BE | 2,000 of 2,000 (100%) | ||
| be-best-address-brussels | BE | 2,000 of 2,000 (100%) | ||
| lu-bd-adresses | LU | 2,000 of 2,000 (100%) | ||
| au-gnaf | AU | 2,000 of 2,000 (100%) | ||
| lv-valsts-adresu-registrs | LV | 2,000 of 2,000 (100%) | ||
| de-berlin-adressen | DE | 2,000 of 2,000 (100%) | ||
| de-nrw-gebaeudereferenzen | DE | 2,000 of 2,000 (100%) | ||
| de-rlp-hauskoordinaten | DE | 2,000 of 2,000 (100%) | ||
| dk-danmarks-adresser | DK | 2,000 of 2,000 (100%) | ||
| br-cnefe-2022 · 27 files | BR | 54,000 of 54,000 (100%) |
The coverage column is the publisher’s own claim about its file, except where we mark a register partial because our copy cannot vouch for an address it lacks — the address data sources page says which and why. Either way it is the coverage the register carries today, not a measurement. Where it is partial, an address the register does not carry answers exists: null — never false — and the not_in_register weight never applies. A register that is not installed here is not in this table at all, and every country without one answers exists: null.
Measured on real business addresses
Every Sunday we draw a seeded sample of up to 2,000 addresses from each company register installed here — registered offices and business addresses as the companies filed them — and send each one through the ordinary lookup, uncharged and unlogged. It measures our matcher on addresses other people wrote, with their abbreviations, building names and missing postcodes. It is not coverage: business addresses skew urban and towards formation agents, so the sample is not a country’s addresses, and a miss can be our parser’s reading of a line or the company’s spelling as easily as a gap in a register. The report keeps counts only — nothing about any single address or company. Last run 2026-10-18.
| Company register | Country | Sampled | Building | Street | Postcode only | Not found | No register here | Refused as written |
|---|---|---|---|---|---|---|---|---|
| uk-companies-house | GB | 0.0% | 75.4% | 0.0% | 22.0% | 1.9% | 0.7% | |
| us-co-business-entities | US | 51.3% | 40.6% | 6.3% | 1.6% | 0.0% | 0.2% | |
| us-ny-business-entities | US | 65.3% | 25.6% | 6.9% | 1.6% | 0.0% | 0.6% | |
| us-or-business-entities | US | 90.5% | 3.6% | 5.9% | 0.0% | 0.0% | 0.0% | |
| fr-sirene-establishments | FR | 74.3% | 11.5% | 14.2% | 0.0% | 0.0% | 0.0% | |
| with an INSEE address identifier | 81.1% | 11.6% | 7.3% | 0.0% | 0.0% | 0.0% | ||
| without one | 11.7% | 10.6% | 77.7% | 0.0% | 0.0% | 0.0% | ||
| no-enhetsregisteret | NO | 95.6% | 1.3% | 3.0% | 0.1% | 0.0% | 0.0% | |
| us-ct-business-entities | US | 73.2% | 20.2% | 5.4% | 0.9% | 0.1% | 0.2% | |
| us-hi-business-registrations | US | 0.1% | 72.9% | 0.0% | 26.9% | 0.1% | 0.0% |
Building means an address register — a national one, or a German Land’s — found the building itself; street, that it found the street, or placed the number inside a range the Census Bureau publishes; postcode only, that it knew the postcode and not the street. Great Britain’s register lists streets, never buildings, so street is the furthest a British address can get. No register here means no register of that country is installed on this server, so there was nothing to match against; refused as written means the lookup answered valid: false. Each filing is sent as the separate fields its register’s reader takes out of it, the way a customer would send them; a French establishment goes as INSEE’s own address columns, with the street type spelled out. Every row adds up to 100%.
The Brønnøysund register shares its business addresses with Matrikkelen, the register that answers Norwegian lookups here, so the Norwegian row mostly tests our own key folding rather than how people write an address.
INSEE gives most French establishments an address identifier from its own address matching, so the rows it identified and the rows it did not are counted apart: finding an address INSEE has already matched is close to circular.
Where one credit pays for itself.
See through a registered office
companies_registered and is_mail_drop tell you when the address on a supplier form is a formation agent’s counter rather than an office — and mail_drop_source says which of the three sources decided, so you can set your own threshold.
What a registered-agent address isFix an address before you ship
A typed reason names the missing part or the malformed postcode, formatted hands back the address the way the operator writes it, confirmation says which parts a dataset stood behind, changes says what was normalised, and street_suggestion names the street the register meant when the one typed is not there.
Fill a street picker from a postcode
GET /api/v1/address/streets answers every street a national register lists inside a postcode in one call, so a checkout form filters locally as the visitor types. Open data only, wherever a register with streets is installed.
Gate a checkout with one boolean
ok_to_ship and blocked_by apply your own shipping policy — which signals block, how high the score may go, whether a register must have confirmed the building — to every answer, so a checkout branches on one field and the reason is named beside it. The score stays arithmetic over flags in the same response for anyone who would rather write the rules themselves.
Catch the address nobody meant to give
looks_placeholder flags a street or town typed to get past the form — asdf, n/a, no address, a keyboard run — and unit_check says when a flat number is missing at a building the register lists many units at, or written at a single residence. Both come from the same lookup, with the weights published.
What we won’t pretend to know.
Address data is where a confident-looking boolean sells best. Ours says null when nothing was evaluated, and the response names the datasets that were.
Two answers are licensed, and neither is switched on
Whether post is actually delivered to an address — with the postal service’s own agency, vacant and residential flags — and which buildings sit at a UK postcode are both licensed data; every full UK address list derives from the Royal Mail Postcode Address File. Both sit behind a driver that is not configured: deliverability answers "not checked", and a British postcode lists the streets Ordnance Survey files under its district, never a building, rather than a guess. What open data does answer is said as what it is: a building’s position, use and units come from the register that publishes them, never from an inference.
Absence from a partial register proves nothing
exists is true only on a building match, and false only when the register that answered has complete coverage. Where coverage is partial — for example in the United States and France, whose registers are fed by whoever chose to take part, or in Denmark, where our copy of the register, taken on 26 September 2026, is no longer refreshed — an address that is not in it answers null, and the not_in_register weight never applies. Absence from a partial register is not evidence that an address does not exist.
A mismatch is only scored where the directory lists every name
A town the directory lists elsewhere in the postcode’s area, or a US ZIP whose directory carries only the default city and the Census places whose land it covers, reads locality_matches_postcode false without a weight, and confirmation says which case it is. A register’s postcodes augment a directory and never replace it, so box-only codes a register of buildings never lists keep answering; that is also why no country becomes complete by augmentation alone.
The decision is yours, and it says why
ok_to_ship comes from the shipping policy your account holds — the published defaults until you change them — and blocked_by names the one rule that decided. An address that cannot stand as written is blocked whatever the policy says. Nothing here is a verdict about a person.
A mail drop is a fact about an address, not a person
It means an operator publishes the address as one of its branches, that a registered-agent or formation service publishes it or a public listing or filing naming the service carries it, or that more companies are registered there than the published threshold. mail_drop_source says which. Plenty of honest businesses use one, and nothing here says who lives or works anywhere.
What counts as a mail dropCommon questions about address lookups.
Do you know whether post is actually delivered there?
Not from open data, and we do not pretend otherwise. That answer — with the postal service’s own agency, vacant and residential flags — is licensed in every country that sells it. The request flag deliverability, the response fields deliverability_checked, is_deliverable, is_cmra, is_vacant and is_residential, and their billing are all fixed now, so nothing changes for your client when a partner is signed. Until then the check answers deliverability_checked: false and costs nothing extra.
Can I get the list of addresses at a postcode?
The streets, yes, wherever a national register with a street listing is installed: GET /api/v1/address/streets answers every street the register lists inside a postcode in one call, and GET /api/v1/address/postcode/{postcode} answers the same list in the address-picker shape. The buildings at a UK postcode are the exception: every full UK address list derives from the Royal Mail Postcode Address File and needs a licence, so while no licensed partner is configured a British postcode answers the streets Ordnance Survey files under its district, never the buildings on them. A country no installed register covers answers 501 ADDRESS_LIST_UNAVAILABLE, and so does a postcode the listing cannot speak for — a Northern Irish BT, forces BFPO or BF1, or non-geographic BX code, a district Ordnance Survey files no street under, a German postcode outside Berlin, or a Czech postcode whose addresses are on no named street — with a message saying why; nothing is charged. What open data does answer for a British address is in a normal lookup — whether the postcode is live or terminated, its centroid and local authority, whether the street is one Ordnance Survey lists in that district, and whether the town is one the postcode is written with.
What do confirmation and changes tell me?
confirmation names, for the postcode, the street, the house number, the town and the region, the dataset that stood behind it — a postcode directory, a register, a published number range, a company register, an operator’s branch list — or unconfirmed when a dataset that could have confirmed the part did not, or null when nothing could check it. changes lists what the parser moved or set aside on the way from your input to the parts: a last line that only repeated the country, a c/o line, a building name separated from the street, a state folded onto its code, a box line moved into po_box. Nothing is normalised silently.
How do you know an address is a private mailbox?
From the way the postal service requires it to be written. A box rented at a mail-receiving agency is addressed with a PMB number after a real street address, and that is exactly what address_type: private_mailbox reports, with address_type_source: address_rules. It is a reading of the address, not a licensed flag — an agency address written without the PMB, or with a bare # that reads as a suite, reads as an ordinary street address, and we would rather say that than invent a match.
What does exists: null mean?
That no register answered about the building. Either no register covers the country, or the register that does is partial — it covers only part of the country, or its copy cannot vouch for every address — and this address is not in what it carries. Null means not evaluated, never no: a country with no register installed answers null, never false, and match_level tells you how close the lookup got — premise, street, postcode or none.
Which countries can you answer for?
Every country has its format and postcode pattern, so the shape of an address is checked in 207 of them. 52 postal operators’ box naming is carried, so a box, a private mailbox, general delivery, a rural route, military mail, a parcel locker or a CEDEX is recognised in those. Thirteen countries have a national register of buildings behind exists — the United States, France, Switzerland, Austria, Czechia, Norway, Belgium, Luxembourg, Australia, Latvia, Denmark, the Netherlands and Brazil, with New Zealand where a LINZ key is configured, and Berlin, North Rhine-Westphalia and Rhineland-Palatinate each carry a partial register — Great Britain has a register of streets, the United States adds the Census Bureau’s number ranges, and postcode directories cover Great Britain and about a hundred other countries. Every response names exactly the datasets it used, and a server that has not synced one of them answers null for it rather than guessing.
Can the answer make the decision for me?
Yes. Every answer ends with ok_to_ship and blocked_by, decided by your account’s shipping policy: the signals that block whenever they fire, a ceiling on the risk score, and whether a register must have confirmed the building. The defaults block above 60 and on undeliverable, placeholder and vacant; change them with PUT /api/v1/address/policy or in the dashboard’s Shipping policy tab, and every lookup, batch, bulk row and monitor applies the new policy at once. An address that cannot stand as written is never ok to ship, and blocked_by says invalid.
What is a placeholder?
What somebody types to get past a form without giving an address: asdf, test, n/a, none, no address, same as above, a keyboard run, a name with no vowel, one character repeated. looks_placeholder is true only when the whole street name or the whole town is one of those — Test Valley Road and Sample Road are real streets and are never flagged — and the placeholder weight of 60 is in the default block list.
Why does seen_by_you never count other customers?
seen_by_you counts how many times your own account looked the same address up inside the last seven days, under the premise digest rather than the address, and never reads anybody else’s lookups. A postal address is where somebody lives, and a pooled record of who is checking it would be a database about residences — the same line address verification draws for outcome reports.
Do you tell me who lives at an address?
No. Nothing in the response is about a person: no resident, no occupancy, no name at an address. The product is about places — what kind of delivery point this is, whether it stands as written, and what the public registers say about it. No field will ever say who is there.
What costs a credit?
One credit for a fresh answer where valid is true. An address that cannot stand as written costs nothing, and so does a repeat of the same address within seven days — the repeat marker is keyed on the address as the pipeline folds it, so two spellings of one address are one lookup and one charge. Asking for deliverability adds premium credits only when the partner actually answered.
Guides
All guides- How to tell a UK virtual-office or formation address from a trading address
- A suite at a single-family home
- Gate a checkout with the shipping policy
- Placeholder addresses: what people type instead of an address
- Reading a British postcode district page
- What a postcode directory learns from a register
- A registered agent's address is not a mail drop, and not a home
- How an open register locates a building
- How to read the address confirmation map
- Number ranges: what the US range match can and cannot say
- What a street match means in Great Britain
- Can you look up UK addresses from a postcode for free?
- How to read an address-existence answer
- What a PMB (private mailbox) is, and why it cannot prove where you live
Check your first address in minutes.
Create a key, send one POST request, and keep free lookups every month on us.