Autocomplete JS Library Migration

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

Both libraries provide address autocomplete functionality that can be dropped into HTML pages, but differ in their initialization patterns, configuration options, and event handling.

There are two major versions of the GetAddress autocomplete library (1.x and 2.x). This guide covers migration from both versions.

Key Differences

Feature	GetAddress.io 1.x/2.x	Ideal Postcodes
CDN Script	getaddress-autocomplete-*.js	address-finder-bundled
Initialization	getAddress.autocomplete()	AddressFinder.setup()
Auto-binding (v1)	Automatic via output_fields	Automatic via outputFields
Auto-binding (v2)	Manual via event listener	Automatic via outputFields

Which Version Are You Using?

Check your script tag to determine your GetAddress.io version:

<!-- Version 1.x -->
<script src="https://cdn.getaddress.io/scripts/getaddress-autocomplete-1.*.js"></script>

<!-- Version 2.x -->
<script src="https://cdn.getaddress.io/scripts/getaddress-autocomplete-2.*.js"></script>

---

Migrating from GetAddress.io 1.x

GetAddress.io version 1.x automatically binds address fields using the output_fields configuration option.

Complete Example: Before & After

GetAddress.io 1.x

<form>
  <input id="line_1" type="text" />
  <input id="line_2" type="text" />
  <input id="line_3" type="text" />
  <input id="town_or_city" type="text" />
  <input id="postcode" type="text" />
</form>

<script src="https://cdn.getaddress.io/scripts/getaddress-autocomplete-1.3.0.min.js"></script>
<script>
  getAddress.autocomplete("line_1", "YOUR_API_KEY", {
    output_fields: {
      line_2: "line_2",
      line_3: "line_3",
      town_or_city: "town_or_city",
      postcode: "postcode",
    },
  });
</script>

Ideal Postcodes

<script src="https://cdn.jsdelivr.net/npm/@ideal-postcodes/address-finder-bundled@4"></script>
<form>
  <input id="line_1" type="text" />
  <input id="line_2" type="text" />
  <input id="line_3" type="text" />
  <input id="town" type="text" />
  <input id="postcode" type="text" />
</form>

<script>
  IdealPostcodes.AddressFinder.setup({
    apiKey: "YOUR_API_KEY",
    outputFields: {
      line_1: "#line_1",
      line_2: "#line_2",
      line_3: "#line_3",
      post_town: "#town",
      postcode: "#postcode",
    },
  });
</script>

Step-by-Step Migration (1.x)

Step 1: Replace CDN Script

GetAddress.io 1.x

<script src="https://cdn.getaddress.io/scripts/getaddress-autocomplete-1.3.0.min.js"></script>

Ideal Postcodes

<script src="https://cdn.jsdelivr.net/npm/@ideal-postcodes/address-finder-bundled@4"></script>

Step 2: Update Initialization Code

GetAddress.io 1.x

getAddress.autocomplete("line_1", "YOUR_API_KEY", {
  output_fields: {
    line_2: "line_2",
    line_3: "line_3",
    town_or_city: "town_or_city",
    postcode: "postcode",
  },
});

Ideal Postcodes

IdealPostcodes.AddressFinder.setup({
  apiKey: "YOUR_API_KEY",
  outputFields: {
    line_1: "#line_1",
    line_2: "#line_2",
    line_3: "#line_3",
    post_town: "#town",
    postcode: "#postcode",
  },
});

Key Changes:

• Function name: getAddress.autocomplete() → IdealPostcodes.AddressFinder.setup()
• API key: Second parameter → apiKey property
• Fields are identified in an object called outputFields

Step 3: Update Field Names

GetAddress.io and Ideal Postcodes use different field names for certain address components. Use the Address Field Mapping Reference to update your field names.

Migrating from GetAddress.io 2.x

GetAddress.io version 2.x requires manual field binding via event listeners. Ideal Postcodes simplifies this with automatic field binding.

Complete Example

GetAddress.io 2.x

<script src="https://cdn.getaddress.io/scripts/getaddress-autocomplete-2.0.2.min.js"></script>
<form>
  <input type="text" id="line1" placeholder="Search address" />
  <input id="line2" type="text" />
  <input id="line3" type="text" />
  <input id="line4" type="text" />
  <input id="line5" type="text" />
  <input id="postcode" type="text" />
</form>

<script>
  const autocomplete = getAddress.autocomplete("line1", "YOUR_API_KEY");

  // Manual field binding required
  autocomplete.addEventListener(
    "getaddress-autocomplete-address-selected",
    function (e) {
      document.getElementById("line1").value =
        e.address.formatted_address[0];
      document.getElementById("line2").value =
        e.address.formatted_address[1];
      document.getElementById("line3").value =
        e.address.formatted_address[2];
      document.getElementById("line4").value =
        e.address.formatted_address[3];
      document.getElementById("line5").value =
        e.address.formatted_address[4];
      document.getElementById("postcode").value = e.address.postcode;
    },
  );
</script>

Ideal Postcodes

<script src="https://cdn.jsdelivr.net/npm/@ideal-postcodes/address-finder-bundled@4"></script>
<form>
  <input type="text" id="line1" placeholder="Search address" />
  <input id="line2" type="text" />
  <input id="line3" type="text" />
  <input id="town" type="text" />
  <input id="postcode" type="text" />
</form>

<script>
  // Automatic field binding
  IdealPostcodes.AddressFinder.setup({
    apiKey: "YOUR_API_KEY",
    outputFields: {
      line_1: "#line1",
      line_2: "#line2",
      line_3: "#line3",
      post_town: "#town",
      postcode: "#postcode",
    },
  });
</script>

Step-by-Step Migration (2.x)

Step 1: Replace CDN Script

GetAddress.io 2.x

<script src="https://cdn.getaddress.io/scripts/getaddress-autocomplete-2.0.2.min.js"></script>

Ideal Postcodes

<script src="https://cdn.jsdelivr.net/npm/@ideal-postcodes/address-finder-bundled@4"></script>

Step 2: Simplify Field Binding

GetAddress.io 2.x requires manual field binding via event listeners. Ideal Postcodes handles this automatically:

GetAddress.io 2.x

const autocomplete = getAddress.autocomplete("line1", "YOUR_API_KEY");

autocomplete.addEventListener(
  "getaddress-autocomplete-address-selected",
  function (e) {
    document.getElementById("line1").value = e.address.formatted_address[0];
    document.getElementById("line2").value = e.address.formatted_address[1];
    document.getElementById("line3").value = e.address.formatted_address[2];
    document.getElementById("town").value = e.address.town_or_city;
    document.getElementById("postcode").value = e.address.postcode;
  },
);

Ideal Postcodes (Automatic Binding)

IdealPostcodes.AddressFinder.setup({
  apiKey: "YOUR_API_KEY",
  outputFields: {
    line_1: "#line1",
    line_2: "#line2",
    line_3: "#line3",
    post_town: "#town",
    postcode: "#postcode",
  },
});

Step 3: Update Field Names

GetAddress.io and Ideal Postcodes use different field names for certain address components. Use the Address Field Mapping Reference to update your field names.

Migrate Event Handling

All the events generated by v1 and v2 of the GetAddress.io autocomplete library can be handled using Address Finder callbacks.

See the Address Finder events documentation for all available callbacks.

Links

• Address Finder Documentation
• Address Finder Configuration Options
• Address Finder Callback Options

Need Help?

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