Validation Migration

Overview

This guide helps you migrate from GetAddress's Validate API to Ideal Postcodes' Cleanse API.

Both APIs validate and cleanse freeform address input, returning a standardised address with geocoding data. Ideal Postcodes provides richer match quality indicators and includes UPRN data.

Key Differences

Feature	GetAddress Validate	Ideal Postcodes Cleanse
Endpoint	GET/POST /validate/{address}	POST /v1/cleanse/addresses
Authentication	Query param api-key	Header Authorization: api_key="..."
Request format	Address in URL path	JSON body
Match quality	HTTP status codes (200/300/404)	Confidence score + match indicators
Geocoding	Included	Included
UPRN	Not included	Included

Authentication

GetAddress:

GET https://api.getAddress.io/validate/{address}?api-key=YOUR_KEY

Ideal Postcodes:

curl -X POST 'https://api.ideal-postcodes.co.uk/v1/cleanse/addresses?api_key=YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"query": "10 Downing Street, London"}'

Or using the Authorization header:

curl -X POST 'https://api.ideal-postcodes.co.uk/v1/cleanse/addresses' \
  -H 'Authorization: api_key="YOUR_KEY"' \
  -H 'Content-Type: application/json' \
  -d '{"query": "10 Downing Street, London"}'

Request Format

GetAddress accepts address as a URL path parameter:

GET https://api.getAddress.io/validate/91 Salcott Road, London?api-key=YOUR_KEY

Ideal Postcodes accepts a JSON body with optional structured fields:

{
  "query": "91 Salcott Road, London",
  "postcode": "SW11 6DF", // optional
  "post_town": "London" // optional
}

Providing additional fields like postcode and post_town improves match accuracy.

Response Mapping

GetAddress Response (200)

{
  "postcode": "SW11 6DF",
  "latitude": 51.4619,
  "longitude": -0.1583,
  "formatted_address": ["91 Salcott Road", "", "", "London", "Greater London"],
  "thoroughfare": "Salcott Road",
  "building_name": "",
  "sub_building_name": "",
  "building_number": "91",
  "line_1": "91 Salcott Road",
  "line_2": "",
  "line_3": "",
  "line_4": "",
  "locality": "",
  "town_or_city": "London",
  "county": "Greater London",
  "district": "Wandsworth",
  "country": "England",
  "residential": true
}

Ideal Postcodes Response

{
  "code": 2000,
  "message": "Success",
  "result": {
    "query": "91 Salcott Road, London",
    "confidence": 0.95,
    "fit": 1,
    "count": 1,
    "organisation_match": "NA",
    "premise_match": "FULL",
    "thoroughfare_match": "FULL",
    "postcode_match": "MISSING",
    "locality_match": "NA",
    "post_town_match": "FULL",
    "match": {
      "postcode": "SW11 6DF",
      "latitude": 51.4619123,
      "longitude": -0.1583456,
      "line_1": "91 Salcott Road",
      "line_2": "",
      "line_3": "",
      "post_town": "LONDON",
      "thoroughfare": "Salcott Road",
      "building_name": "",
      "sub_building_name": "",
      "building_number": "91",
      "dependant_locality": "",
      "county": "",
      "district": "Wandsworth",
      "ward": "Shaftesbury and Queenstown",
      "country": "England",
      "uprn": "10091859876",
      "udprn": 27399182
    }
  }
}

Field Mapping Reference

GetAddress Field	Ideal Postcodes Field
postcode	result.match.postcode
latitude	result.match.latitude
longitude	result.match.longitude
line_1	result.match.line_1
line_2	result.match.line_2
line_3	result.match.line_3
line_4	N/A (use post_town)
thoroughfare	result.match.thoroughfare
building_name	result.match.building_name
sub_building_name	result.match.sub_building_name
building_number	result.match.building_number
locality	result.match.dependant_locality
town_or_city	result.match.post_town
county	result.match.county
district	result.match.district
country	result.match.country
residential	N/A
N/A	result.match.uprn
N/A	result.match.udprn
N/A	result.match.ward

Handling Match Quality

GetAddress uses HTTP status codes:

• 200 - Single address found
• 300 - Multiple addresses found (when strict=true)
• 404 - No address found

Ideal Postcodes always returns 200 with match quality indicators:

const response = await fetch(url);
const data = await response.json();

if (data.result.match === null) {
  // No match found (equivalent to GetAddress 404)
  console.log("Address not found");
} else if (data.result.confidence < 0.5) {
  // Low confidence match - review manually
  console.log("Weak match, manual review needed");
} else if (data.result.count > 1) {
  // Multiple matches found (similar to GetAddress 300)
  console.log("Multiple matches, closest returned");
} else {
  // Good match
  console.log("Address validated:", data.result.match);
}

Match Level Indicators

Ideal Postcodes provides granular match quality for each address component:

Value	Meaning
FULL	Exact match
PARTIAL	Close but not exact (e.g. typo corrected)
INCORRECT	Input doesn't match suggestion
MISSING	Input missing this element
NA	Element not applicable to this address
NO_MATCH	No match found

Use these to understand which parts of the address were validated:

if (result.postcode_match === "FULL" && result.premise_match === "FULL") {
  // High confidence - exact premise and postcode match
}

Code Examples

JavaScript/Node.js

Before (GetAddress):

const address = encodeURIComponent("91 Salcott Road, London");
const response = await fetch(
  `https://api.getAddress.io/validate/${address}?api-key=${apiKey}`,
);

if (response.status === 200) {
  const data = await response.json();
  console.log(data.postcode, data.line_1);
} else if (response.status === 404) {
  console.log("Address not found");
}

After (Ideal Postcodes):

const response = await fetch(
  `https://api.ideal-postcodes.co.uk/v1/cleanse/addresses?api_key=${apiKey}`,
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ query: "91 Salcott Road, London" }),
  },
);

const data = await response.json();

if (data.result.match) {
  console.log(data.result.match.postcode, data.result.match.line_1);
  console.log("Confidence:", data.result.confidence);
} else {
  console.log("Address not found");
}

Python

Before (GetAddress):

import requests
from urllib.parse import quote

address = quote("91 Salcott Road, London")
response = requests.get(
    f"https://api.getAddress.io/validate/{address}",
    params={"api-key": api_key}
)

if response.status_code == 200:
    data = response.json()
    print(data["postcode"], data["line_1"])

After (Ideal Postcodes):

import requests

response = requests.post(
    "https://api.ideal-postcodes.co.uk/v1/cleanse/addresses",
    params={"api_key": api_key},
    json={"query": "91 Salcott Road, London"}
)

data = response.json()
if data["result"]["match"]:
    match = data["result"]["match"]
    print(match["postcode"], match["line_1"])
    print("Confidence:", data["result"]["confidence"])

Key Differences

1. Richer match quality data: Ideal Postcodes returns confidence scores and per-field match indicators, giving you more control over validation thresholds.

2. UPRN included: Every matched UK address includes its Unique Property Reference Number (UPRN), useful for property-level deduplication and integration with other datasets.

3. Structured input option: Separate postcode and post_town fields can improve match accuracy for ambiguous addresses.

4. No strict parameter: Ideal Postcodes always returns the closest match with a count of alternatives. Use confidence and count to implement your own strictness logic.

5. No residential flag: This field is not available in the Cleanse API response.

Further Reading

• Cleanse API Reference
• Understanding Confidence Scores
• Browser Address Cleanse Tool
• Field Mapping Reference