Address Field Mapping Reference

Overview

This guide provides a comprehensive reference for mapping GetAddress.io address fields to their Ideal Postcodes equivalents.

Address Structure Comparison

Both GetAddress.io and Ideal Postcodes return structured address data, but with some key differences:

• Address Lines: GetAddress.io uses 4 address lines (line_1 through line_4), while Ideal Postcodes uses 3 (line_1, line_2, line_3)
• Field Naming: Some fields have been renamed for clarity (e.g., town_or_city → post_town, locality → dependant_locality)
• Additional Fields: Ideal Postcodes provides additional geographic and administrative data (UPRN, UDPRN, eastings, northings)

Complete Field Mapping Table

GetAddress.io Field	Ideal Postcodes Field	Notes
postcode	postcode	Direct match
latitude	latitude	Direct match
longitude	longitude	Direct match
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	line_3	Can be dropped as Ideal Postcodes fits 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	Not provided; construct 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

Additional Fields Available

Ideal Postcodes provides additional fields not available in GetAddress.io:

Ideal Postcodes Field	Description
uprn	Unique Property Reference Number
udprn	Unique Delivery Point Reference Number
eastings	Ordnance Survey eastings coordinate
northings	Ordnance Survey northings coordinate
postcode_inward	Inward part of postcode (e.g., "7SY")
postcode_outward	Outward part of postcode (e.g., "GU2")
ward	Electoral ward
traditional_county	Traditional county name
administrative_county	Administrative county name
postal_county	Postal county name

Migration Code Examples

Basic Field Mapping

From: GetAddress.io

function formatAddress(address) {
  return {
    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: address.postcode,
  };
}

To: Ideal Postcodes

function formatAddress(address) {
  return {
    line1: address.line_1,
    line2: address.line_2,
    line3: address.line_3,
    line4: "", // We provide a 3 line format
    town: address.post_town,
    county: address.county,
    postcode: address.postcode,
    // Bonus: Access to additional data
    uprn: address.uprn,
    udprn: address.udprn,
  };
}

Handling the Formatted Address

GetAddress.io provides a formatted_address array with 5 elements. If you need this format with Ideal Postcodes, you can construct it:

function createFormattedAddress(address) {
  return [
    address.line_1,
    address.line_2,
    address.line_3,
    address.post_town,
    address.county,
  ].filter((line) => line && line.trim() !== "");
}

Complete Migration Helper

Here's a complete helper function that maps all common fields:

function migrateGetAddressToIdealPostcodes(getAddressData) {
  return {
    // Direct mappings
    postcode: getAddressData.postcode,
    latitude: getAddressData.latitude,
    longitude: getAddressData.longitude,
    thoroughfare: getAddressData.thoroughfare,
    building_number: getAddressData.building_number,
    building_name: getAddressData.building_name,
    sub_building_name: getAddressData.sub_building_name,
    line_1: getAddressData.line_1,
    line_2: getAddressData.line_2,
    line_3: getAddressData.line_3,
    county: getAddressData.county,
    district: getAddressData.district,
    country: getAddressData.country,

    // Renamed fields
    post_town: getAddressData.town_or_city,
    dependant_locality: getAddressData.locality,

    // Fields not available in GetAddress.io
    uprn: null,
    udprn: null,
    eastings: null,
    northings: null,
  };
}

TypeScript Type Definitions

If you're using TypeScript, here are type definitions to help with migration:

// GetAddress.io address type
interface GetAddressAddress {
  postcode: string;
  latitude: number;
  longitude: number;
  formatted_address: [string, string, string, string, string];
  thoroughfare: string;
  building_name: string;
  sub_building_name: string;
  sub_building_number: string;
  building_number: string;
  line_1: string;
  line_2: string;
  line_3: string;
  line_4: string;
  locality: string;
  town_or_city: string;
  county: string;
  district: string;
  country: string;
  residential: boolean;
}

// Ideal Postcodes address type
interface IdealPostcodesAddress {
  postcode: string;
  postcode_inward: string;
  postcode_outward: string;
  post_town: string;
  dependant_locality: string;
  double_dependant_locality: string;
  thoroughfare: string;
  dependant_thoroughfare: string;
  building_number: string;
  building_name: string;
  sub_building_name: string;
  po_box: string;
  department_name: string;
  organisation_name: string;
  udprn: number;
  postcode_type: string;
  su_organisation_indicator: string;
  delivery_point_suffix: string;
  line_1: string;
  line_2: string;
  line_3: string;
  premise: string;
  longitude: number;
  latitude: number;
  eastings: number;
  northings: number;
  country: string;
  traditional_county: string;
  administrative_county: string;
  postal_county: string;
  county: string;
  district: string;
  ward: string;
  uprn: string;
  id: string;
  country_iso: string;
  country_iso_2: string;
  county_code: string;
  language: string;
  umprn: string;
  dataset: string;
}

Need Help?

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