Autocomplete Migration

Overview

This guide helps you migrate from GetAddress.io's Autocomplete API to Ideal Postcodes' Address Finder API.

Both APIs a two-step process for autocomplete, which involve getting address suggestions given user input and then resolving the selected suggestion into a full address.

Key Differences

Feature	GetAddress.io	Ideal Postcodes
Endpoint	/autocomplete/{term}	/v1/autocomplete/addresses
Authentication	api-key parameter	api_key parameter

Migration Steps

1. Update Address Suggestion Endpoint

GetAddress.io:

GET https://api.getaddress.io/autocomplete/{term}?api-key=YOUR_KEY

Ideal Postcodes (Step 1 - Get Suggestions):

GET https://api.ideal-postcodes.co.uk/v1/autocomplete/addresses?query={term}&api_key=YOUR_KEY

2. Map to Ideal Postcodes Suggestion ID

GetAddress.io Format:

{
  "suggestions": [
    {
      "address": "10 Downing Avenue, Guildford, Surrey, GU2 7SY",
      "url": "/get/VGp4ZzNrNXZMbVJ5OG1UcWg3YjJGNA",
      "id": "VGp4ZzNrNXZMbVJ5OG1UcWg3YjJGNA"
    },
    {
      "address": "10 Downing Close, Bradford, West Yorkshire, BD3 0QT",
      "url": "/get/UXdlOXJwTDJuNGNaM3hKaDF2OGtTNg",
      "id": "UXdlOXJwTDJuNGNaM3hKaDF2OGtTNg"
    }
  ]
}

Ideal Postcodes Format:

{
  "result": {
    "hits": [
      {
        "id": "paf_10093397",
        "suggestion": "10 Downing Avenue, Guildford, GU2",
        "udprn": 10093397,
        "urls": {
          "udprn": "/v1/udprn/10093397"
        }
      },
      {
        "id": "paf_1550664",
        "suggestion": "10 Downing Close, Bradford, BD3",
        "udprn": 1550664,
        "urls": {
          "udprn": "/v1/udprn/1550664"
        }
      }
    ]
  },
  "code": 2000,
  "message": "Success"
}

Conversion

When migrating your code, update the response parsing:

GetAddress.io:

// Access suggestions
const suggestions = data.suggestions;
const firstSuggestion = suggestions[0];
const displayText = firstSuggestion.address;
const suggestionId = firstSuggestion.id;

Ideal Postcodes:

// Access suggestions
const suggestions = data.result.hits;
const firstSuggestion = suggestions[0];
const displayText = firstSuggestion.suggestion;
const suggestionId = firstSuggestion.id;

Key mapping:

• data.suggestions → data.result.hits
• suggestion.address → hit.suggestion
• suggestion.id → hit.id (use directly for resolve endpoint)

3. Update Address Resolve Endpoint

GetAddress.io Suggestion Request

GET https://api.getAddress.io/get/{id}?api-key={api-key}

GetAddress.io Format

{
    "postcode": "NN1 3ER",
    "latitude": 52.24593734741211,
    "longitude": -0.891636312007904,
    "formatted_address": [
        "10 Watkin Terrace",
        "",
        "",
        "Northampton",
        "Northamptonshire"
     ],
    "thoroughfare":  "Watkin Terrace",
    "building_name":  "",
    "sub_building_name":  "",
    "sub_building_number":  "",
    "building_number":  "10",
    "line_1":  "10 Watkin Terrace",
    "line_2":  "",
    "line_3":  "",
    "line_4":  "",
    "locality":  "",
    "town_or_city":  "Northampton",
    "county":  "Northamptonshire",
    "district":  "Northampton",
    "country":  "England"
    "residential":  true
}

Ideal Postcodes Suggestion Request

GET https://api.ideal-postcodes.co.uk/v1/autocomplete/addresses/{address_id}/gbr?api_key=YOUR_KEY

{
  "postcode": "GU2 7SY",
  "postcode_inward": "7SY",
  "postcode_outward": "GU2",
  "post_town": "Guildford",
  "dependant_locality": "",
  "double_dependant_locality": "",
  "thoroughfare": "Downing Avenue",
  "dependant_thoroughfare": "",
  "building_number": "10",
  "building_name": "",
  "sub_building_name": "",
  "po_box": "",
  "department_name": "",
  "organisation_name": "",
  "udprn": 10093397,
  "postcode_type": "S",
  "su_organisation_indicator": "",
  "delivery_point_suffix": "2D",
  "line_1": "10 Downing Avenue",
  "line_2": "",
  "line_3": "",
  "premise": "10",
  "longitude": -0.6002693,
  "latitude": 51.2385077,
  "eastings": 497810,
  "northings": 149745,
  "country": "England",
  "traditional_county": "Surrey",
  "administrative_county": "Surrey",
  "postal_county": "Surrey",
  "county": "Surrey",
  "district": "Guildford",
  "ward": "Onslow",
  "uprn": "100061387496",
  "id": "paf_10093397",
  "country_iso": "GBR",
  "country_iso_2": "GB",
  "county_code": "",
  "language": "en",
  "umprn": "",
  "dataset": "paf"
}

Field Mapping

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

Migration Example:

// Before: 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,
  };
}

// After: Ideal Postcodes
function formatAddress(address) {
  return {
    line1: address.line_1,
    line2: address.line_2,
    line3: address.line_3,
    line4: "", // Ideal Postcodes only provides 3 lines
    town: address.post_town, // Changed from town_or_city
    county: address.county,
    postcode: address.postcode,
    // Bonus: Access to additional data
    uprn: address.uprn,
    udprn: address.udprn,
  };
}

Need Help?

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