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	Check if organisation_name is present
sub_building_number	N/A	Check for a numeric element within sub_building_name

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 fixed 7-element comma-separated format:

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

Position-to-Field Mapping:

Array Position	GetAddress.io Field	Maps to IDPC 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 (more accurate)
• Access to additional data (UPRN, UDPRN, eastings, northings)

Migration Code Examples

Simple Format

From: GetAddress.io

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(", ");

    return {
      line1: parts[0] || "",
      line2: parts[1] || "",
      line3: parts[2] || "",
      line4: parts[3] || "",
      locality: parts[4] || "",
      town: parts[5] || "",
      county: parts[6] || "",
      postcode: data.postcode,
      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: "", // We provide a 3 line format
    locality: address.dependant_locality,
    town: address.post_town,
    county: address.county,
    postcode: address.postcode,
    latitude: address.latitude,
    longitude: address.longitude,
    // Bonus: Access to additional data
    uprn: address.uprn,
    udprn: address.udprn,
    eastings: address.eastings,
    northings: address.northings,
  }));
}

Expanded Format

From: GetAddress.io

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,
  }));
}

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: "", // Ideal Postcodes fits addresses in 3 lines
    locality: address.dependant_locality, // Changed from locality
    town: address.post_town, // Changed from Town/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.