Address verification
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.
10 free lookups a 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.
Response fields
Every field, documented.
This is the actual contract of POST /api/v1/address — 45 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. | ||
| organization | The company line, when one was sent or recognised in the written address. | ||
| 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 or mailbox line, including a private-mailbox number lifted out of the street line. | ||
| po_box | The box line as the operator writes it, in that country’s own words. A box written on the street line moves here. | ||
| 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_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. | ||
| 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. | ||
| locality_matches_postcode | Whether the town written on the address is the town the directory publishes for that postcode. Null when either is unknown. | ||
| 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 publisher claims to list every address does not carry it. Null otherwise — including when the register covers only part of the country. | ||
| match_level | How far the address could be followed into that register: premise, street, postcode or none. Null when no register covers the country. | ||
| register / register_coverage | Which register answered and how complete its publisher says it is: complete or partial. Read exists against this, always. | ||
| latitude / longitude / location_source | The centroid the postcode directory publishes for that postcode, and the fact that it is a postcode centroid rather than a rooftop. Null where no directory covers the country. | ||
| companies_registered | How many companies name this address in an open company register. 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 as a branch when an operator does, and which of the two sources answered: operator_list or company_cluster. | ||
| 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. | ||
| 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. |
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
$ 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, "risk_score": 60, "risk_level": "high", "risk_signals": [{ "signal": "private_mailbox", "weight": 60, … }], "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 or # number after a real street address. |
| 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. The address is a routing instruction, not a place. |
| parcel_locker | An automated parcel machine such as a Packstation or a Paczkomat. |
| bulk_mail | A business-volume arrangement that replaces the street address: the French CEDEX, TSA and CS, the Dutch Antwoordnummer. |
| unknown | We carry no box naming for that country, so nothing was classified. Not the same answer as street. |
Risk score
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 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 postcode the directory has terminated | +30 |
| The town does not match the one the directory publishes for the postcode | +30 |
| Not in a register whose publisher lists every address | +20 |
| A business-volume arrangement such as a CEDEX | +20 |
Data sources
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.
| Dataset | Covers | Refreshed | Licence |
|---|---|---|---|
| address-formats | What an address needs in 206 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, as the states and local authorities that take part share them with the Department of Transportation. Coverage is partial, and the response says so. | ||
| fr-base-adresse-nationale | Addresses in France and its overseas regions, from the Base Adresse Nationale (IGN/DINUM). | ||
| ch-gebaeudeadressverzeichnis | The official directory of building addresses for Switzerland and Liechtenstein. | ||
| at-adressregister | Austria’s address register, from the Bundesamt für Eich- und Vermessungswesen. | ||
| cz-ruian-adresni-mista | Czechia’s RÚIAN address points, from the Czech Office for Surveying, Mapping and Cadastre. | ||
| no-matrikkelen-adresse | Norway’s addresses from Matrikkelen, the national property register kept by Kartverket. | ||
| ons-postcode-directory | Every Great Britain postcode with its status, the dates it was introduced and terminated, its centroid and its published town. Northern Ireland postcodes are excluded: reusing them needs a separate Land & Property Services licence. | ||
| uk-companies-house | The registered office of every UK company, from the free company data product, counted per address. | ||
| company-registers (US) | Principal and registered-agent addresses from the Colorado, New York and Oregon business registries, counted the same way. | ||
| mail-drop-locations | The branch addresses mailbox and mail-forwarding operators publish themselves, so a match can name the operator. |
Use cases
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 two sources decided, so you can set your own threshold.
Fix 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, and where a directory publishes a town for the postcode, locality_matches_postcode catches the one that was typed from memory.
Score a checkout address
A post-office box, a private mailbox or a terminated postcode is worth a second look on a high-value order. The score is arithmetic over flags in the same response, so your rules can use the flags instead.
The honest part
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 addresses 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, so they answer "not checked" and a 501 rather than a guess.
Absence from a partial register proves nothing
exists is true only on a building match, and false only when the register that answered claims to list every address. Where coverage is partial — the United States and France, whose registers are fed by whoever chose to take part — 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 mail drop is a fact about an address, not a person
It means an operator publishes the address as one of its branches, 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.
FAQ
Address lookups, specifically
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 UK postcode?
Not yet. GET /api/v1/address/postcode/{postcode} exists and answers 501 ADDRESS_LIST_UNAVAILABLE while no licensed partner is configured, because every full UK address list derives from the Royal Mail Postcode Address File and needs a licence. What open data does answer for a British postcode is already in a normal lookup: whether the postcode is live or terminated, when it was introduced or terminated, its centroid, and the local authority it sits in. It cannot answer the town: the ONS directory publishes no post town, which is why locality_matches_postcode stays null in Great Britain.
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 or # 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 number 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 covers only part of it and this address is not in the part 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 206 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. Six countries have a national address register behind exists — the United States, France, Switzerland, Austria, Czechia and Norway — and Great Britain has the ONS postcode directory behind postcode_status and the centroid. Every response names exactly the datasets it used.
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.
Check your first address in minutes.
Create a key, send one POST request, and keep 10 lookups a month on us.