# jQuery Plugin Migration

This guide helps you migrate from GetAddress's jQuery Find plugin to Ideal Postcodes' [jquery.postcodes](https://github.com/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[​](#key-similarities--differences "Direct link to 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[​](#complete-example-before--after "Direct link to Complete Example: Before & After")

### GetAddress jQuery[​](#getaddress-jquery "Direct link to 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[​](#ideal-postcodes-jquery "Direct link to 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-by-step-migration "Direct link to Step-by-Step Migration")

### Step 1: Replace Script[​](#step-1-replace-script "Direct link to Step 1: Replace Script")

#### GetAddress jQuery[​](#getaddress-jquery-1 "Direct link to GetAddress jQuery")

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

#### Ideal Postcodes jQuery[​](#ideal-postcodes-jquery-1 "Direct link to Ideal Postcodes jQuery")

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

### Step 2: Update Initialization[​](#step-2-update-initialization "Direct link to Step 2: Update Initialization")

#### GetAddress jQuery[​](#getaddress-jquery-2 "Direct link to 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[​](#ideal-postcodes-jquery-2 "Direct link to 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[​](#step-3-update-field-names "Direct link to 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](/docs/migrate/getaddressio/field-mapping.md).

## Migrating Callbacks[​](#migrating-callbacks "Direct link to 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[​](#callback-migration-example "Direct link to Callback Migration Example")

#### GetAddress jQuery[​](#getaddress-jquery-3 "Direct link to 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[​](#ideal-postcodes-jquery-3 "Direct link to 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[​](#configuration-options-mapping "Direct link to 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[​](#additional-configuration-options "Direct link to 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[​](#using-custom-input-and-button "Direct link to Using Custom Input and Button")

Both plugins support using existing form elements:

#### GetAddress jQuery[​](#getaddress-jquery-4 "Direct link to 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[​](#ideal-postcodes-jquery-4 "Direct link to 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.

## Links[​](#links "Direct link to Links")

* [jquery.postcodes on GitHub](https://github.com/ideal-postcodes/jquery.postcodes)
* [jquery.postcodes on npm](https://www.npmjs.com/package/jquery-postcodes)
* [Postcode Lookup (Modern Alternative)](/docs/postcode-lookup.md)
* [Address Field Mapping Reference](/docs/migrate/getaddressio/field-mapping.md)

## Need Help?[​](#need-help "Direct link to Need Help?")

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