# Address Field Mapping Reference ## Overview[​](#overview "Direct link to Overview") This guide provides a comprehensive reference for mapping GetAddress address fields to their Ideal Postcodes equivalents. ## Address Structure Comparison[​](#address-structure-comparison "Direct link to Address Structure Comparison") Both GetAddress and Ideal Postcodes return structured address data, but with some key differences: * **Address Lines**: GetAddress 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[​](#complete-field-mapping-table "Direct link to Complete Field Mapping Table") | GetAddress 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` | N/A | Not used; 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 | Not provided; construct from line\_1, line\_2, line\_3 | | `residential` | Derived | Check if `organisation_name` and `po_box` are empty | | `sub_building_number` | N/A | Not provided as separate field | ## Additional Fields Available[​](#additional-fields-available "Direct link to Additional Fields Available") Ideal Postcodes provides additional fields not available in GetAddress: | 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[​](#migration-code-examples "Direct link to Migration Code Examples") ### Basic Field Mapping[​](#basic-field-mapping "Direct link to Basic Field Mapping") #### From: GetAddress[​](#from-getaddress "Direct link to From: GetAddress") ``` 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[​](#to-ideal-postcodes "Direct link to 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[​](#handling-the-formatted-address "Direct link to Handling the Formatted Address") GetAddress 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[​](#complete-migration-helper "Direct link to 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 uprn: null, udprn: null, eastings: null, northings: null, }; } ``` ## TypeScript Type Definitions[​](#typescript-type-definitions "Direct link to TypeScript Type Definitions") If you're using TypeScript, here are type definitions to help with migration: ``` // GetAddress 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?[​](#need-help "Direct link to Need Help?") We are available 9am to 5pm UK time on chat or email for migration assistance.