jQuery Plugin Migration

This guide helps you migrate from GetAddress's jQuery Find plugin to Ideal Postcodes' jquery.postcodes plugin.

Both plugins provide postcode lookup functionality for jQuery-based forms, allowing users to enter a postcode and select their address from a dropdown list.

Key Similarities & Differences

Feature	GetAddress jQuery	Ideal Postcodes jQuery
jQuery Version	jQuery 2+	jQuery 1.9+
Initialization	`$().getAddress()`	`$().setupPostcodeLookup()`
Field Binding	CSS selectors via `output_fields`	CSS selectors via `output_fields`

Complete Example: Before & After

GetAddress jQuery

<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
<script src="https://cdn.getaddress.io/scripts/jquery.getAddress-4.0.0.js"></script>
<form>
  <div id="postcode_lookup"></div>

  <label>Address Line 1</label>
  <input id="line1" type="text" />

  <label>Address Line 2</label>
  <input id="line2" type="text" />

  <label>Address Line 3</label>
  <input id="line3" type="text" />

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

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

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

<script>
  $("#postcode_lookup").getAddress({
    api_key: "YOUR_GETADDRESS_API_KEY",
    output_fields: {
      line_1: "#line1",
      line_2: "#line2",
      line_3: "#line3",
      post_town: "#town",
      county: "#county",
      postcode: "#postcode",
    },
  });
</script>

Ideal Postcodes jQuery

<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/jquery-postcodes@3/dist/postcodes.min.js"></script>
<form>
  <div id="postcode_lookup"></div>

  <label>Address Line 1</label>
  <input id="line1" type="text" />

  <label>Address Line 2</label>
  <input id="line2" type="text" />

  <label>Address Line 3</label>
  <input id="line3" type="text" />

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

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

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

<script>
  $("#postcode_lookup").setupPostcodeLookup({
    api_key: "YOUR_IDEAL_POSTCODES_API_KEY",
    output_fields: {
      line_1: "#line1",
      line_2: "#line2",
      line_3: "#line3",
      post_town: "#town",
      county: "#county",
      postcode: "#postcode",
    },
  });
</script>

Step-by-Step Migration

Step 1: Replace Script

GetAddress jQuery

<script src="https://cdn.getaddress.io/scripts/jquery.getAddress-4.0.0.js"></script>

Ideal Postcodes jQuery

<script src="https://cdn.jsdelivr.net/npm/jquery-postcodes@3/dist/postcodes.min.js"></script>

Step 2: Update Initialization

GetAddress jQuery

$("#postcode_lookup").getAddress({
  api_key: "YOUR_GETADDRESS_API_KEY",
  output_fields: {
    line_1: "#line1",
    line_2: "#line2",
    line_3: "#line3",
    post_town: "#town",
    county: "#county",
    postcode: "#postcode",
  },
});

Ideal Postcodes jQuery

$("#postcode_lookup").setupPostcodeLookup({
  api_key: "YOUR_IDEAL_POSTCODES_API_KEY",
  output_fields: {
    line_1: "#line1",
    line_2: "#line2",
    line_3: "#line3",
    post_town: "#town",
    county: "#county",
    postcode: "#postcode",
  },
});

Key Changes:

Method name: .getAddress() → .setupPostcodeLookup()
API key: Replace with your Ideal Postcodes API key
Field mapping: Uses same output_fields structure with CSS selectors

Step 3: Update Field Names

The field names are largely compatible. The main difference is town_or_city in GetAddress maps to post_town in Ideal Postcodes:

GetAddress Field	Ideal Postcodes Field	Description
`line_1`	`line_1`	First address line
`line_2`	`line_2`	Second address line
`line_3`	`line_3`	Third address line
`post_town`	`post_town`	Town/City
`county`	`county`	County
`postcode`	`postcode`	Postcode

For additional field mappings, see the Address Field Mapping Reference.

Migrating Callbacks

Both plugins support callbacks, but with different names and signatures:

GetAddress Callback	Ideal Postcodes Callback	Description
`onLookupSuccess`	`onAddressesRetrieved`	Addresses returned from API
`onLookupError`	`onSearchError`	API returned an error
`onAddressSelected`	`onAddressSelected`	User selected an address
N/A	`onSearchCompleted`	Search completed (success/fail)
N/A	`onLoaded`	Plugin initialized
N/A	`onFailedCheck`	API key validation failed
N/A	`onDropdownCreated`	Dropdown added to DOM
N/A	`onDropdownDestroyed`	Dropdown removed from DOM
N/A	`onLookupTriggered`	User clicked search button
N/A	`shouldLookupTrigger`	Control whether lookup proceeds

Callback Migration Example

GetAddress jQuery

$("#postcode_lookup").getAddress({
  api_key: "YOUR_API_KEY",
  output_fields: {
    line_1: "#line1",
    post_town: "#town",
    postcode: "#postcode",
  },
  onLookupSuccess: function (data) {
    console.log("Found addresses:", data);
  },
  onLookupError: function () {
    console.log("Lookup failed");
  },
  // Receives { id, text } object
  onAddressSelected: function (selected) {
    console.log("Selected:", selected.text);
  },
});

Ideal Postcodes jQuery

$("#postcode_lookup").setupPostcodeLookup({
  api_key: "YOUR_API_KEY",
  output_fields: {
    line_1: "#line1",
    post_town: "#town",
    postcode: "#postcode",
  },
  onAddressesRetrieved: function (addresses) {
    console.log("Found addresses:", addresses);
  },
  onSearchError: function (error) {
    console.log("Lookup failed:", error);
  },
  // Receives full address object
  onAddressSelected: function (address) {
    console.log("Selected:", address.line_1);
  },
});

Key Differences:

onLookupSuccess → onAddressesRetrieved: Both receive array of addresses
onLookupError → onSearchError: Ideal Postcodes passes error object with details
onAddressSelected: GetAddress passes { id, text } object, Ideal Postcodes passes the full address object with all fields

Configuration Options Mapping

Most configuration options have direct equivalents:

GetAddress Option	Ideal Postcodes Option	Notes
`api_key`	`api_key`	Direct match
`input`	`input`	Direct match
`input_label`	`input_label`	Direct match
`input_class`	`input_class`	Direct match
`input_id`	`input_id`	Direct match
`input_muted_style`	`input_muted_style`	Direct match
`button`	`button`	Direct match
`button_label`	`button_label`	Direct match
`button_class`	`button_class`	Direct match
`button_id`	`button_id`	Direct match
`button_disabled_message`	`button_disabled_message`	Direct match
`dropdown_id`	`dropdown_id`	Direct match
`dropdown_class`	`dropdown_class`	Direct match
`dropdown_select_message`	`dropdown_select_message`	Direct match
`error_message_postcode_invalid`	`error_message_invalid_postcode`	Renamed
`error_message_postcode_not_found`	`error_message_not_found`	Renamed
`error_message_default`	`error_message_default`	Direct match
`error_message_class`	`error_message_class`	Direct match
`lookup_interval`	`disable_interval`	Renamed (same functionality)
`timeout`	N/A	Fixed at 10000ms
`input_name`	N/A	Not supported

Additional Configuration Options

Ideal Postcodes jquery.postcodes supports additional configuration not available in GetAddress:

$("#postcode_lookup").setupPostcodeLookup({
  api_key: "YOUR_API_KEY",
  output_fields: {
    line_1: "#line1",
    line_2: "#line2",
    line_3: "#line3",
    post_town: "#town",
    postcode: "#postcode",
  },

  // API Configuration
  endpoint: "https://api.ideal-postcodes.co.uk/v1", // Custom API endpoint
  licensee: "your_licensee_key", // Optional licensee key
  tags: ["source:website"], // Request tagging for analytics

  // Behaviour
  check_key: true, // Validate API key on init
  remove_organisation: true, // Remove org names from address lines
  address_search: false, // Enable fallback to address search
  debug_mode: false, // Show API errors to user

  // Custom Containers
  dropdown_container: "#custom_dropdown_area",
  error_message_container: "#custom_error_area",
});

Using Custom Input and Button

Both plugins support using existing form elements:

GetAddress jQuery

$("#postcode_lookup").getAddress({
  api_key: "YOUR_API_KEY",
  input: "#my_postcode_input",
  button: "#my_search_button",
  output_fields: {
    line_1: "#line1",
    post_town: "#town",
    postcode: "#postcode",
  },
});

Ideal Postcodes jQuery

$("#postcode_lookup").setupPostcodeLookup({
  api_key: "YOUR_API_KEY",
  input: "#my_postcode_input",
  button: "#my_search_button",
  output_fields: {
    line_1: "#line1",
    post_town: "#town",
    postcode: "#postcode",
  },
});

Both plugins use the same input and button options to reference existing elements.

Need Help?

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

Key Similarities & Differences​

Complete Example: Before & After​

GetAddress jQuery​

Ideal Postcodes jQuery​

Step-by-Step Migration​

Step 1: Replace Script​

GetAddress jQuery​

Ideal Postcodes jQuery​

Step 2: Update Initialization​

GetAddress jQuery​

Ideal Postcodes jQuery​

Step 3: Update Field Names​

Migrating Callbacks​

Callback Migration Example​

GetAddress jQuery​

Ideal Postcodes jQuery​

Configuration Options Mapping​

Additional Configuration Options​

Using Custom Input and Button​

GetAddress jQuery​

Ideal Postcodes jQuery​

Links​

Need Help?​

Key Similarities & Differences

Complete Example: Before & After

GetAddress jQuery

Ideal Postcodes jQuery

Step-by-Step Migration

Step 1: Replace Script

GetAddress jQuery

Ideal Postcodes jQuery

Step 2: Update Initialization

GetAddress jQuery

Ideal Postcodes jQuery

Step 3: Update Field Names

Migrating Callbacks

Callback Migration Example

GetAddress jQuery

Ideal Postcodes jQuery

Configuration Options Mapping

Additional Configuration Options

Using Custom Input and Button

GetAddress jQuery

Ideal Postcodes jQuery

Links

Need Help?