Legacy v2 API Migration

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

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

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

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

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

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

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

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

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

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 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

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 for more details.

Need Help?

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