# Installing Address Validation & Postcode Lookup for Adobe Commerce (Magento) This guide walks you through installing and configuring the Ideal Postcodes address lookup extension for Adobe Commerce (Magento). The extension enables postcode lookup or address finder at checkout, account address forms, and in the admin panel. ## Overview[​](#overview "Direct link to Overview") **What this integration provides:** * Real-time UK address validation and postcode lookup * Enhanced checkout experience with faster address entry * Reduced delivery errors and customer support tickets **Extension Compatibility:** * ✅ Mageplaza One Step Checkout * ✅ OneStepCheckout.com Extension **Choose Your Method:** Use the plugin for Address Validation or UK Postcode Lookup to enhance your checkout experience – making it easier for customers to enter addresses quickly and accurately. If unsure which method is best, read our [Address Finder vs Postcode Lookup comparison guide](https://ideal-postcodes.co.uk/guides/postcode-lookup-vs-address-finder) or [watch the video](https://www.youtube.com/watch?v=2l6armAn25k). ## Where Address Lookup is Applied[​](#where-address-lookup-is-applied "Direct link to Where Address Lookup is Applied") The extension adds address validation or postcode lookup to: * **Checkout Billing Form** - Customer billing address entry * **Checkout Shipping Form** - Customer shipping address entry * **Customer Address Form** - Account address book management * **Admin Order Address** - Administrative order creation/editing You can enable or disable each location individually in the configuration panel. ## 1. Sign up for a Free Trial and Get Your API Key[​](#1-sign-up-for-a-free-trial-and-get-your-api-key "Direct link to 1. Sign up for a Free Trial and Get Your API Key") Before installing the extension, you'll need an Ideal Postcodes API Key. **Steps:** 1. Sign up for a free account at [ideal-postcodes.co.uk/sign-up](https://ideal-postcodes.co.uk/sign-up) 2. Navigate to the **KEYS** section in your account 3. Copy your API Key - you'll need this to complete the setup in Adobe Commerce. It's a string of characters that begins with the letters `ak` 💡 **All new accounts include 50 free test credits - no payment required.** ## 2. Install the Adobe Commerce (Magento) Extension[​](#2-install-the-adobe-commerce-magento-extension "Direct link to 2. Install the Adobe Commerce (Magento) Extension") You can install the Adobe Commerce (Magento) extension in one of three ways: ### Method A: Install via Adobe Commerce (Magento) Marketplace (Recommended)[​](#method-a-install-via-adobe-commerce-magento-marketplace-recommended "Direct link to Method A: Install via Adobe Commerce (Magento) Marketplace (Recommended)") **Best for:** Users who prefer GUI installation and automatic updates. Install directly from the Adobe Commerce (Magento) Marketplace. This is the simplest way to integrate address validation. **Steps:** 1. **Access Marketplace:** Go to the [Ideal Postcodes marketplace listing](https://marketplace.magento.com/idealpostcodes-module-ukaddresssearch.html) 2. **Add Extension:** Click **Add to Cart** (it's free) 3. **Select Version:** Choose your version and edition (the latest version is always available in the marketplace) 4. **Complete Order:** Click **Place Order** 5. **Install:** Check all is correct and click **INSTALL** 6. **Follow Instructions:** Follow the **How to Install** instructions on the right 7. **Next Step:** Proceed to [Step 3: Configure the Extension](#3-configure-the-extension) **Estimated Time:** 5-10 minutes ### Method B: Install via Composer (Direct)[​](#method-b-install-via-composer-direct "Direct link to Method B: Install via Composer (Direct)") **Best for:** Developers comfortable with command line and version control. **Prerequisites:** * Composer installed and configured * SSH/terminal access to your Magento server * Magento maintenance mode recommended **Step 1: Install Package** ``` # Install the Ideal Postcodes extension via Composer composer require idealpostcodes/module-ukaddresssearch ``` **Step 2: Enable and Configure Module** ``` # Enable the module in Magento bin/magento module:enable Idealpostcodes_Ukaddresssearch # Update database schema and configuration bin/magento setup:upgrade # Compile dependency injection code for production bin/magento setup:di:compile # Deploy static content files (force deployment) bin/magento setup:static-content:deploy -f # Clear cache bin/magento cache:flush ``` **Estimated Time:** 10-15 minutes ### Method C: Manual Installation[​](#method-c-manual-installation "Direct link to Method C: Manual Installation") To install manually, place the extension in the following directory within your Magento project: ``` app/code/Idealpostcodes/Ukaddressessearch ``` You can populate this directory using one of the following methods: **Download from GitHub Releases** 1. Visit the [GitHub releases page](https://github.com/ideal-postcodes/magento/releases) 2. Download the archive for the desired version 3. Extract it into `app/code/Idealpostcodes/Ukaddressessearch` **Clone the Repository** ``` # Clone the latest version from GitHub $ git clone --depth=1 https://github.com/ideal-postcodes/magento.git ``` **Clone a Specific Version** ``` # Clone a specific tagged version (replace with version number) $ git clone --branch --depth=1 https://github.com/ideal-postcodes/magento.git ``` After the files are in place, run the following to complete the installation: ``` # Enable the module and complete installation magento module:enable Idealpostcodes_Ukaddresssearch magento setup:upgrade magento setup:di:compile magento setup:static-content:deploy -f ``` ## 3. Configure the Extension[​](#3-configure-the-extension "Direct link to 3. Configure the Extension") Once the extension is installed, it's time to configure it. Here's how: ![Configuration Screenshot](https://img.ideal-postcodes.co.uk/magento-configuration-stores-1.png) In your Adobe Commerce (Magento) Admin Panel: **Go to:** Stores → Configuration → Services → Ideal Postcodes ### Required Settings[​](#required-settings "Direct link to Required Settings") **Enable the Extension:** Set **Enabled (store view)** to **Yes** to activate the extension. **Enter Your API Key:** Paste the API Key you copied when signing up. You can always retrieve it from the **KEYS** section of your Ideal Postcodes account. 💡 **Tip:** Give the key a clear, descriptive name (e.g. "Shipping Address") so it's easy to identify if you create multiple keys later. ### Enable Address Lookup in Your Store[​](#enable-address-lookup-in-your-store "Direct link to Enable Address Lookup in Your Store") Configure where you want address validation to appear: 1. Go to **Store Configuration** 2. Enable either **Postcode Lookup** or **Address Autocomplete**, depending on your preference, by selecting **Yes** under each section ### Hoist Country Field[​](#hoist-country-field "Direct link to Hoist Country Field") This setting moves the Country field to the top of your address form. It's useful if your store's default country is not a UK territory. Our UK address search (Postcode Lookup and Autocomplete) will only appear on forms where the selected country is a UK territory (e.g. United Kingdom, Jersey, Guernsey, Isle of Man). By placing the Country field first, you ensure users select a UK territory before address lookup is triggered. ### Enable in Admin (Orders)[​](#enable-in-admin-orders "Direct link to Enable in Admin (Orders)") To enable address lookup in the Magento Admin area (orders): 1. Open **Store Admin Configuration** 2. Set **Enable Address Autocomplete** to **Yes** 💾 **Don't forget to click Save Config to apply your changes.** ### Advanced Settings[​](#advanced-settings "Direct link to Advanced Settings") You can also adjust additional settings to suit your store's specific needs. ![Advanced Configuration Screenshot](https://img.ideal-postcodes.co.uk/idpc-options.png) ### Custom Fields Configuration[​](#custom-fields-configuration "Direct link to Custom Fields Configuration") **When to use:** If you have custom checkout forms or third-party extensions that modify address fields. **Configuration Format:** Add this JSON configuration to map your custom form fields to our address lookup: ``` [ { "line_1": "input[name='billing_street0']", // CSS selector for first address line field "line_2": "input[name='billing_street1']", // CSS selector for second address line field "line_3": "input[name='street[2]']", // CSS selector for third address line field (optional) "post_town": "input[name='billing_city']", // CSS selector for city/town field "county": "input[name='billing_county']", // CSS selector for county/region field (optional) "postcode": "input[name='billing_postcode']" // CSS selector for postcode field } ] ``` **How to find CSS selectors:** 1. Open your checkout page 2. Right-click on an address field → "Inspect Element" 3. Copy the `name` attribute value 4. Format as `input[name='ATTRIBUTE_VALUE']` **Save any changes made.** For additional key settings such as daily lookup limits or URL restrictions, check out our documentation on the [API Key](/docs/guides/api-key-settings.md). ## 4. Test the Integration[​](#4-test-the-integration "Direct link to 4. Test the Integration") To make sure the address validation works: 1. Go to your Adobe Commerce checkout page 2. Begin typing an address or postcode in the address field 3. The Ideal Postcodes address autocomplete tool should suggest addresses ## 5. Troubleshooting[​](#5-troubleshooting "Direct link to 5. Troubleshooting") | Issue | Solution | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | No address suggestions appear | • Verify API Key is correct and active
• Check key balance in your account dashboard
• Ensure country is set to UK territory | | Extension not visible in admin | • Run installation commands: `magento module:enable Idealpostcodes_Ukaddresssearch`
• Clear cache: `php bin/magento cache:flush`
• Recompile: `php bin/magento setup:di:compile` | | JavaScript errors in browser | • Check browser console (F12) for specific errors
• Test with default Magento theme
• Disable other extensions to identify conflicts | | Address fields not populating | • Verify custom field mapping in Advanced Settings
• Check CSS selectors match your form structure
• Review logs at `var/log/system.log` or `exception.log` | info Need help? Contact our support team via live chat on our website or email .