# Legacy v2 API Migration

## Overview[​](#overview "Direct link to Overview")

This guide helps you migrate from GetAddress's **Legacy v2 API** to Ideal Postcodes' **Postcodes API**.

The v2 API was an older GetAddress endpoint that retrieved addresses for a UK postcode.

## GetAddress v2 API Reference[​](#getaddress-v2-api-reference "Direct link to GetAddress v2 API Reference")

### Endpoints[​](#endpoints "Direct link to Endpoints")

| Method | Endpoint                                             | Description                                          |
| ------ | ---------------------------------------------------- | ---------------------------------------------------- |
| GET    | `https://api.getAddress.io/v2/uk/{postcode}`         | Returns all addresses for a postcode                 |
| GET    | `https://api.getAddress.io/v2/uk/{postcode}/{house}` | Returns address for a postcode and house name/number |

### Query Parameters[​](#query-parameters "Direct link to Query Parameters")

| Parameter | Required | Description                 | Type       |
| --------- | -------- | --------------------------- | ---------- |
| `api-key` | Yes      | Your API key                | Text       |
| `format`  | No       | Formats addresses as arrays | True/False |

### Response Format[​](#response-format "Direct link to Response Format")

```
{

  "Latitude": 52.24593734741211,

  "Longitude": -0.891636312007904,

  "Addresses": [

    "10 Watkin Terrace, , , , , Northampton, Northamptonshire",

    "12 Watkin Terrace, , , , , Northampton, Northamptonshire"

  ]

}
```

Each address string follows a **fixed 7-element comma-separated format**:

```
"line1,line2,line3,line4,locality,Town/City,County"
```

## Key Differences[​](#key-differences "Direct link to Key Differences")

| Feature            | GetAddress v2           | Ideal Postcodes             |
| ------------------ | ----------------------- | --------------------------- |
| **Endpoint**       | `/v2/uk/{postcode}`     | `/v1/postcodes/{postcode}`  |
| **Authentication** | `api-key` parameter     | `api_key` parameter         |
| **Response Root**  | `Addresses` array       | `result` array              |
| **Address Format** | Comma-separated string  | Structured JSON object      |
| **Coordinates**    | Per-postcode            | Per-address (more accurate) |
| **Field Names**    | PascalCase (`Latitude`) | snake\_case (`latitude`)    |

## Migration Steps[​](#migration-steps "Direct link to Migration Steps")

### 1. Update Endpoint[​](#1-update-endpoint "Direct link to 1. Update Endpoint")

**GetAddress v2:**

```
GET https://api.getAddress.io/v2/uk/NN1 3ER?api-key=YOUR_KEY
```

**Ideal Postcodes:**

```
GET https://api.ideal-postcodes.co.uk/v1/postcodes/NN1 3ER?api_key=YOUR_KEY
```

### 2. Update Response Parsing[​](#2-update-response-parsing "Direct link to 2. Update Response Parsing")

**Position-to-Field Mapping:**

| Array Position | GetAddress Field | Ideal Postcodes Field |
| -------------- | ---------------- | --------------------- |
| `address[0]`   | line1            | `line_1`              |
| `address[1]`   | line2            | `line_2`              |
| `address[2]`   | line3            | `line_3`              |
| `address[3]`   | line4            | (not used, 3 lines)   |
| `address[4]`   | locality         | `dependant_locality`  |
| `address[5]`   | Town/City        | `post_town`           |
| `address[6]`   | County           | `county`              |

**Key Changes:**

* `data.Addresses` → `data.result`
* String parsing → Direct property access
* Single lat/lng for postcode → Individual lat/lng per address
* Access to additional data (UPRN, UDPRN, eastings, northings)

## Migration Code Examples[​](#migration-code-examples "Direct link to Migration Code Examples")

### From: GetAddress v2[​](#from-getaddress-v2 "Direct link to From: GetAddress v2")

```
async function lookupPostcode(postcode) {

  const response = await fetch(

    `https://api.getAddress.io/v2/uk/${postcode}?api-key=${API_KEY}`,

  );

  const data = await response.json();



  return data.Addresses.map((address) => {

    const parts = address.split(", ");



    return {

      line1: parts[0] || "",

      line2: parts[1] || "",

      line3: parts[2] || "",

      line4: parts[3] || "",

      locality: parts[4] || "",

      town: parts[5] || "",

      county: parts[6] || "",

      latitude: data.Latitude,

      longitude: data.Longitude,

    };

  });

}
```

### To: Ideal Postcodes[​](#to-ideal-postcodes "Direct link to To: Ideal Postcodes")

```
async function lookupPostcode(postcode) {

  const response = await fetch(

    `https://api.ideal-postcodes.co.uk/v1/postcodes/${postcode}?api_key=${API_KEY}`,

  );

  const data = await response.json();



  return data.result.map((address) => ({

    line1: address.line_1,

    line2: address.line_2,

    line3: address.line_3,

    line4: "",

    locality: address.dependant_locality,

    town: address.post_town,

    county: address.county,

    postcode: address.postcode,

    latitude: address.latitude,

    longitude: address.longitude,

    // Additional data available

    uprn: address.uprn,

    udprn: address.udprn,

  }));

}
```

## Filtering by House Name/Number[​](#filtering-by-house-namenumber "Direct link to Filtering by House Name/Number")

GetAddress v2 supported filtering by house name/number in the URL path:

```
GET https://api.getAddress.io/v2/uk/NN1 3ER/10?api-key=YOUR_KEY
```

With Ideal Postcodes, retrieve all addresses and filter client-side, or use our [Address Search API](/docs/api/addresses.md) for more flexible querying:

```
// Option 1: Filter postcode results client-side

async function lookupAddress(postcode, house) {

  const response = await fetch(

    `https://api.ideal-postcodes.co.uk/v1/postcodes/${postcode}?api_key=${API_KEY}`,

  );

  const data = await response.json();



  return data.result.filter(

    (address) =>

      address.building_number === house ||

      address.building_name.includes(house) ||

      address.sub_building_name.includes(house),

  );

}
```

## Testing[​](#testing "Direct link to Testing")

Ideal Postcodes provides test postcodes for development:

| Postcode   | Response                                        |
| ---------- | ----------------------------------------------- |
| `ID1 1QD`  | Returns successful response with test addresses |
| `ID1 KFA`  | Returns 404 not found                           |
| `ID1 CLIP` | Returns 402 insufficient balance                |
| `ID1 CHOP` | Returns 404 invalid key                         |

See our [API key guide](/docs/guides/api-key.md) for more details.

## Need Help?[​](#need-help "Direct link to Need Help?")

We are available 9am to 5pm UK time on chat or email <support@ideal-postcodes.co.uk> for migration assistance.