Find JS Library Migration

This guide helps you migrate from GetAddress.io's Find JavaScript library to Ideal Postcodes' Postcode Lookup JavaScript library.

The GetAddress.io Find library allows users to enter a postcode, then select their address from a dropdown list. The selected address is automatically populated into your form fields.

Ideal Postcodes' Postcode Lookup library provides the same functionality with similar configuration.

Key Differences

Feature	GetAddress.io Find	Ideal Postcodes
CDN Script	getaddress-find-2.1.0.min.js	postcode-lookup-bundled
Initialization	getAddress.find()	PostcodeLookup.setup()
Container Element	Renders into a container div	Renders into a container element
Field Binding	CSS selects via output_fields	CSS selectors via outputFields
Event Handling	Document-level events	Callback functions

Complete Example: Before & After

GetAddress.io Find

<script src="https://cdn.getaddress.io/scripts/getaddress-find-2.1.0.min.js"></script>
<form>
  <!-- Container for postcode lookup widget -->
  <div id="postcode_lookup"></div>

  <label>First Address Line</label>
  <input id="formatted_address_0" type="text" />

  <label>Second Address Line</label>
  <input id="formatted_address_1" type="text" />

  <label>Third Address Line</label>
  <input id="formatted_address_2" type="text" />

  <label>Town</label>
  <input id="formatted_address_3" type="text" />

  <label>County</label>
  <input id="formatted_address_4" type="text" />

  <label>Postcode</label>
  <input id="postcode" type="text" />
</form>

<script>
  getAddress.find("postcode_lookup", "API_KEY", {
    output_fields: {
      formatted_address_0: "formatted_address_0",
      formatted_address_1: "formatted_address_1",
      formatted_address_2: "formatted_address_2",
      formatted_address_3: "formatted_address_3",
      formatted_address_4: "formatted_address_4",
      postcode: "postcode",
    },
  });
</script>

Ideal Postcodes

<script src="https://cdn.jsdelivr.net/npm/@ideal-postcodes/postcode-lookup-bundled@4"></script>
<form>
  <!-- Container for postcode lookup widget -->
  <div id="postcode_lookup"></div>

  <label>First Address Line</label>
  <input id="formatted_address_0" type="text" />

  <label>Second Address Line</label>
  <input id="formatted_address_1" type="text" />

  <label>Third Address Line</label>
  <input id="formatted_address_2" type="text" />

  <label>Town</label>
  <input id="formatted_address_3" type="text" />

  <label>County</label>
  <input id="formatted_address_4" type="text" />

  <label>Postcode</label>
  <input id="postcode" type="text" />
</form>

<script>
  IdealPostcodes.PostcodeLookup.setup({
    apiKey: "API_KEY",
    context: "#postcode_lookup",
    outputFields: {
      line_1: "#formatted_address_0",
      line_2: "#formatted_address_1",
      line_3: "#formatted_address_2",
      post_town: "#formatted_address_3",
      county: "#formatted_address_4",
      postcode: "#postcode",
    },
  });
</script>

Step-by-Step Migration

Step 1: Replace CDN Script

GetAddress.io Find

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

Ideal Postcodes

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

Step 2: Update Initialization Code

GetAddress.io Find

getAddress.find(
  // Identify the container element by ID name:
  "postcode_lookup",
  // Your old GetAddress API Key
  "YOUR_API_KEY",
  {
    output_fields: {
      formatted_address_0: "formatted_address_0",
      formatted_address_1: "formatted_address_1",
      formatted_address_2: "formatted_address_2",
      formatted_address_3: "formatted_address_3",
      postcode: "postcode",
    },
  },
);

Ideal Postcodes

IdealPostcodes.PostcodeLookup.setup({
  // Note `#` is added to reference as an ID:
  context: "#postcode_lookup",
  // Your new Ideal Postcodes API Key goes here:
  apiKey: "YOUR_API_KEY",
  outputFields: {
    line_1: "#formatted_address_0",
    line_2: "#formatted_address_1",
    line_3: "#formatted_address_2",
    post_town: "#formatted_address_3",
    county: "#formatted_address_4",
    postcode: "#postcode",
  },
});

Key Changes:

• Function name: getAddress.find() → IdealPostcodes.PostcodeLookup.setup()
• Container element: First parameter → context property with CSS selector
• API key: Second parameter → apiKey property in configuration object
• Field binding: Element IDs in output_fields → CSS selectors in outputFields
• Selectors: "element_id" → "#element_id" (CSS selector format)
• Field names: Use Ideal Postcodes field names (line_1, post_town, county) but map to existing element IDs

Step 3: Update Field Names

GetAddress.io and Ideal Postcodes use different field names for certain address components. The main difference is that GetAddress.io uses formatted_address array indices, while Ideal Postcodes uses structured field names:

GetAddress.io Field	Ideal Postcodes Field	Description
formatted_address_0	line_1	First address line
formatted_address_1	line_2	Second address line
formatted_address_2	line_3	Third address line
formatted_address_3	post_town	Town/City
formatted_address_4	county	County
locality	dependant_locality	Locality/Village

For additional field mappings (UPRN, geolocation, etc.), see the Address Field Mapping Reference.

Migrating Event Handlers

GetAddress.io Find uses document-level events, while Ideal Postcodes uses callback functions for event handling. See the Postcode Lookup callbacks documentation for all available callbacks.

Migrating Configuration Options

Ideal Postcodes Postcode Lookup supports virtualy all the theming and behavior customizations available in GetAddress.io Find.

For the complete list of configuration options, see the Postcode Lookup configuration documentation.

Links

• Postcode Lookup Documentation
• Postcode Lookup Configuration Options
• Postcode Lookup Callback Options

Need Help?

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