# Validation Migration

## Overview[​](#overview "Direct link to 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[​](#key-differences "Direct link to 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[​](#authentication "Direct link to 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[​](#request-format "Direct link to 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[​](#response-mapping "Direct link to Response Mapping")

### GetAddress Response (200)[​](#getaddress-response-200 "Direct link to 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[​](#ideal-postcodes-response "Direct link to 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[​](#field-mapping-reference "Direct link to 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[​](#handling-match-quality "Direct link to 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[​](#match-level-indicators "Direct link to 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[​](#code-examples "Direct link to Code Examples")

### JavaScript/Node.js[​](#javascriptnodejs "Direct link to 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[​](#python "Direct link to 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[​](#key-differences-1 "Direct link to 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[​](#further-reading "Direct link to Further Reading")

* [Cleanse API Reference](/docs/api/address-cleanse.md)
* [Understanding Confidence Scores](/docs/guides/browser-cleanse.md#confidence)
* [Browser Address Cleanse Tool](/docs/guides/browser-cleanse.md)
* [Field Mapping Reference](/docs/migrate/getaddressio/field-mapping.md)