Postcode Lookup Migration

Overview

This guide helps you migrate from GetAddress.io's Find API to Ideal Postcodes' Postcodes API.

Both APIs retrieve all addresses for a given UK postcode in a single request.

Important: GetAddress.io provides addresses in two formats:

• Simple format (default): Comma-separated string for each address
• Expanded format (?expand=true): Structured JSON objects with individual fields

Ideal Postcodes always returns structured data with individual address components.

Key Differences

Feature	GetAddress.io	Ideal Postcodes
Endpoint	/find/{postcode}	/v1/postcodes/{postcode}
Authentication	api-key parameter	api_key parameter
Response Root	addresses array (top-level)	result array (nested)
Address Format	String or object (requires expand)	Always structured object

Migration Steps

1. Update Postcode Lookup Endpoint

GetAddress.io:

GET https://api.getaddress.io/find/{postcode}?api-key=YOUR_KEY

Ideal Postcodes:

GET https://api.ideal-postcodes.co.uk/v1/postcodes/{postcode}?api_key=YOUR_KEY

2. Update Response Parsing

Option A: Migrating from Expanded Format (Structured Objects)

GetAddress.io Expanded Format (?expand=true):

{
  "postcode": "M1 1AE",
  "latitude": 53.4837226,
  "longitude": -2.2446397,
  "addresses": [
    {
      "formatted_address": [
        "1 Piccadilly Gardens",
        "",
        "",
        "Manchester",
        "Greater Manchester"
      ],
      "thoroughfare": "Piccadilly Gardens",
      "building_name": "",
      "sub_building_name": "",
      "sub_building_number": "",
      "building_number": "1",
      "line_1": "1 Piccadilly Gardens",
      "line_2": "",
      "line_3": "",
      "line_4": "",
      "locality": "",
      "town_or_city": "Manchester",
      "county": "Greater Manchester",
      "district": "Manchester",
      "country": "England",
      "residential": false
    }
  ]
}

Field Mapping Table:

GetAddress.io Field	Ideal Postcodes Field	Notes
postcode	postcode	Direct match
latitude	latitude	Per-postcode → Per-address (more accurate)
longitude	longitude	Per-postcode → Per-address (more accurate)
thoroughfare	thoroughfare	Direct match
building_number	building_number	Direct match
building_name	building_name	Direct match
sub_building_name	sub_building_name	Direct match
line_1	line_1	Direct match
line_2	line_2	Direct match
line_3	line_3	Direct match
line_4	N/A	Ideal Postcodes fits addresses in 3 lines
town_or_city	post_town	Field renamed
county	county	Direct match
district	district	Direct match
country	country	Direct match
locality	dependant_locality	Field renamed
formatted_address	N/A	Build from line_1, line_2, line_3
residential	N/A	Not provided by Ideal Postcodes
sub_building_number	N/A	Not provided as separate field

Option B: Migrating from Simple Format (String Array)

GetAddress.io Simple Format:

{
  "postcode": "SW1A 2AA",
  "latitude": 51.5034066,
  "longitude": -0.1275923,
  "addresses": [
    "10 Downing Street, , , , , London, ",
    "11 Downing Street, , , , , London, ",
    "12 Downing Street, , , , , London, "
  ]
}

Each address string follows this comma-separated format:

• All elements except the last 2 are address lines
• Second to last element is the town/city (post_town)
• Last element is the county

Position-to-Field Mapping:

For an address like "10 Downing Street, , , London, ":

Array Position	Value	Maps to IDPC Field
address[0]	"10 Downing Street"	line_1
address[1]	""	line_2
address[2]	""	line_3
address[n-2]	"London"	post_town
address[n-1]	""	county

Key Changes:

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

3. Migration Code Examples

Before: GetAddress.io (Simple Format)

async function lookupPostcode(postcode) {
  const response = await fetch(
    `https://api.getaddress.io/find/${postcode}?api-key=${API_KEY}`,
  );
  const data = await response.json();

  return data.addresses.map((address) => {
    const parts = address.split(", ");

    // All elements except last 2 are address lines
    const addressLines = parts.slice(0, -2);
    const town = parts[parts.length - 2];
    const county = parts[parts.length - 1];

    return {
      line1: addressLines[0] || "",
      line2: addressLines[1] || "",
      line3: addressLines[2] || "",
      town: town || "",
      county: county || "",
      postcode: data.postcode,
      latitude: data.latitude,
      longitude: data.longitude,
    };
  });
}

Before: GetAddress.io (Expanded Format)

async function lookupPostcode(postcode) {
  const response = await fetch(
    `https://api.getaddress.io/find/${postcode}?api-key=${API_KEY}&expand=true`,
  );
  const data = await response.json();

  return data.addresses.map((address) => ({
    line1: address.line_1,
    line2: address.line_2,
    line3: address.line_3,
    line4: address.line_4,
    town: address.town_or_city,
    county: address.county,
    postcode: data.postcode,
    latitude: data.latitude,
    longitude: data.longitude,
  }));
}

After: 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: "", // Ideal Postcodes fits addresses in 3 lines
    town: address.post_town, // Changed from town_or_city
    county: address.county,
    postcode: address.postcode,
    latitude: address.latitude, // Per-address (more accurate)
    longitude: address.longitude, // Per-address (more accurate)
    // Bonus: Access to additional data
    uprn: address.uprn,
    udprn: address.udprn,
    eastings: address.eastings,
    northings: address.northings,
  }));
}

Need Help?

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