Address verification

Does this address existand does it receive mail?

A failed delivery costs a merchant between 5 and 15 euros, and most of them start with an address that looked fine on the form. This is neither autocomplete nor geocoding.

POST /v1/address

Request

curl https://api.webkitapi.dev/v1/address \
  -H "Authorization: Bearer $WEBKIT_KEY" \
  -d '{"line": "3 Rue de Rivolli, 75004 Paris"}'

Response

{
  "verdict": "corrected",
  "reasons": ["street_corrected"],
  "normalized": {
    "line": "3 Rue de Rivoli, 75004 Paris"
  }
}

What gets checked

A perfect address at a house number that does not exist is still a failed delivery.

  • The street exists in that communeRecognized across accents, hyphens, dropped articles, abbreviations and inverted forms. Postal data uses all of them, and so do your customers.
  • The number is inside the range that is really there999 Rue de Rivoli does not exist, and no format validator will tell you that.
  • The postcode and the commune belong togetherAnd the leading zero every spreadsheet has eaten is put back.
  • Five verdicts, not fourcorrected exists because a postal address is corrected far more often than it is rejected, and folding that case into deliverable would hide the change from whoever has to store it.

Open data

On the Base Adresse Nationale, checkable by you.

Open licence, downloadable in full. The marginal cost of a check becomes a disk read rather than a billed call at somebody else's shop, and that is the entire economic argument for this endpoint.

Provenance is tracked per record from the first day, because upstream sources carry their own attribution requirements and bolting those on later, over a merged table, is misery.

  • You keep the resultNo storage restriction. Cleaning up your customer address table and keeping it is exactly what this is for.
  • Coverage is 0 French departments today. Corsica appears as 20 because that is what its postcodes say. Anything outside them answers postcode_not_covered, which is a gap in our data and not a verdict about your address. The list is read from the database, so it cannot drift from what we actually hold.
  • What we do not claimGoogle really is better on worldwide coverage and on US CASS certification. Pretending otherwise would not survive the first customer.

Questions

Including the awkward answers.

Which countries are covered?
France, from the Base Adresse Nationale, and 0 departments of it so far: . Everywhere else, in France or outside it, the verdict is unknown rather than a guess.
Can I store the normalized addresses?
Yes, without restriction. That is a real difference from providers who tie results to their own services.
Is this autocomplete?
No. Autocomplete suggests while someone types; this endpoint answers afterwards whether the address exists and can receive mail, which is the question that costs money.
What happens if you have no data for a postcode?
The verdict is unknown. The first version answered nonexistent, which declared a perfectly valid address to be fake, and that was a bug.