Address Validation API: Validate an Address in One Request

Eduard Ciociu, Full-Stack Developer

Address Validation API: Validate an Address in One Request

You have an address in a form field or a database column. You want to know whether it is real, get it back in a consistent shape, and store the result. That is one HTTP request, and this article covers what goes into it and what comes back.

If you are still deciding whether you need this at all, what validation actually checks is the better starting point. This page assumes you have decided and are writing the integration.

What an address validation API returns

Three things, in increasing order of usefulness:

  • A verdict. Did this address match, and how well. Treat it as an enum, not a boolean: exact match, corrected match, ambiguous, no match.
  • A normalised address. The components split into fields, cased and spelled consistently, so that two records for the same building compare equal.
  • Enrichment. Coordinates, administrative areas, and identifiers such as a UPRN in Great Britain or a BAG identifier in the Netherlands.

The verdict is what your code branches on. The normalised address is what you store. The enrichment is what makes the call worth making at all, because it is data you did not have before.

Your first request

Almost every address API in this space is REST over HTTPS with JSON responses and an API key. The Pro6PP autocomplete endpoint validates and completes in the same call: you send the postcode and house number, and the full address comes back in structured fields. The full request, the fields in the response and how to handle a failed call are in the developer documentation.

Two decisions to make before you ship this. Call it from your server, not the browser, if the key is billable, because a key in client-side JavaScript is a key anyone can use. And decide what happens when the API is unavailable: for a checkout, the right answer is almost always to let the order through with the unvalidated address and flag it, rather than to lose the sale.

Reading the response: matched, corrected, unverifiable

Handle three cases explicitly.

Exact match. Store the normalised address. Do not store the customer's original string as the address of record, but do keep it somewhere if you may need to explain a change later.

Corrected match. The API found the address but changed something: a misspelled street, a missing town, a reformatted postcode. Show the correction and let the customer accept it. Silently rewriting what someone typed is how you end up delivering to the wrong "High Street".

No match or ambiguous. Do not block. Offer the closest suggestions, and if none fit, let the customer confirm the address as typed and mark the record as unvalidated. New-build properties are the common legitimate case here, and they are exactly the customers you least want to turn away.

Handling partial matches and edge cases

The cases that will bite you, in rough order of frequency:

  • Sub-premises. "Flat 2" and "Apartment 2" and "2/2" can all be the same door. Match at premise level where the data supports it, and store the sub-premise as its own field rather than gluing it onto the street line.
  • Care-of and business names. These are not part of the address and should not be sent for validation. Keep them in a separate recipient field.
  • New builds. Present in reality, absent from the data file. Allow an override.
  • Non-postal addresses. Some locations exist but receive no post. Valid for a service visit, invalid for a delivery.

Bulk validation and rate limits

For a one-off cleanup of an existing database, use the provider's batch route if there is one. If there is not, and you are looping over single requests, three rules keep you out of trouble:

  • Respect the documented rate limit and back off on a 429 rather than retrying immediately.
  • Cache. The same address will appear many times in most customer databases. A local cache keyed on the normalised input can cut a bulk run by a large fraction.
  • Checkpoint. Write results as you go. A batch job that has to start again from zero after an hour is a batch job that will not finish.

Address verification API vs address validation API

The two terms are marketed interchangeably, and most products labelled either one do the same thing: check the address against an authoritative file and return it structured. Where they differ is emphasis. Products sold as verification tend to lean toward data quality, deliverability scoring and batch cleansing. Products sold as validation tend to lean toward real-time capture in a form.

Read the response schema rather than the product name. It will tell you which one you are actually buying.

Where Pro6PP fits

Pro6PP offers address validation, autocomplete and postcode lookup for England, the Netherlands, Belgium, Germany, France, Italy, Luxembourg, Denmark, Austria, Switzerland and Spain, plus global reverse geocoding. The endpoint path carries the country code and the response shape stays the same, so adding a country is a one-character change rather than a second integration.

One English detail worth handling: where a postcode and house number describe more than one building, the API does not guess. It returns the candidates with their identifiers, so you can let the customer pick theirs and look it up again by identifier.

The best-value change you can make alongside validation is to capture the address correctly in the first place, which reduces the number of addresses that need correcting at all. Everything else the API can do sits in our guide to UK address and postcode APIs.

Frequently asked questions

How do I validate an address with an API?

Send the address components, or a single address string, to the provider's validation endpoint with your API key. You get back a match verdict, the address split into normalised fields, and usually coordinates. Branch your code on the verdict rather than treating the response as a simple pass or fail.

What is the difference between an address validation API and an address verification API?

In practice, very little. Both check an address against authoritative data and return it structured. Verification products tend to emphasise batch data quality; validation products tend to emphasise real-time form capture. Compare response schemas, not product names.

Should I validate addresses on the client or the server?

On the server, if your API key is billable or rate limited. A key embedded in client-side JavaScript can be extracted and used by anyone. The exception is a public, domain-restricted key issued specifically for browser use.

What should happen if the address validation API is down?

Let the customer through and mark the address as unvalidated. Blocking a checkout because a third-party service is unavailable converts an infrastructure problem into lost revenue.

Can I validate addresses in bulk through the same API?

Usually yes, either through a dedicated batch endpoint or by looping over the single-address endpoint within the rate limit. Cache repeated addresses and checkpoint your progress.

Next steps