# Postcode Lookup Migration ## Overview[​](#overview "Direct link to Overview") This guide helps you migrate from GetAddress's **Find API** to Ideal Postcodes' **Postcodes API**. Both APIs retrieve all addresses for a given UK postcode in a single request. **Important**: GetAddress 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[​](#key-differences "Direct link to Key Differences") | Feature | GetAddress | 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[​](#migration-steps "Direct link to Migration Steps") ### 1. Update Postcode Lookup Endpoint[​](#1-update-postcode-lookup-endpoint "Direct link to 1. Update Postcode Lookup Endpoint") **GetAddress:** ``` 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[​](#2-update-response-parsing "Direct link to 2. Update Response Parsing") #### Option A: Migrating from Expanded Format (Structured Objects)[​](#option-a-migrating-from-expanded-format-structured-objects "Direct link to Option A: Migrating from Expanded Format (Structured Objects)") **GetAddress 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 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)[​](#option-b-migrating-from-simple-format-string-array "Direct link to Option B: Migrating from Simple Format (String Array)") **GetAddress 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 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[​](#migration-code-examples "Direct link to Migration Code Examples") ### Simple Format[​](#simple-format "Direct link to Simple Format") ### From: GetAddress[​](#from-getaddress "Direct link to From: GetAddress") ``` 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[​](#to-ideal-postcodes "Direct link to 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[​](#expanded-format "Direct link to Expanded Format") ### From: GetAddress[​](#from-getaddress-1 "Direct link to From: GetAddress") ``` 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[​](#to-ideal-postcodes-1 "Direct link to 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?[​](#need-help "Direct link to Need Help?") We are available 9am to 5pm UK time on chat or email for migration assistance.