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

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 or watch the video.

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

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
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

You can install the Adobe Commerce (Magento) extension in one of three ways:

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
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

Estimated Time: 5-10 minutes

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

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
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 <tag> with version number)
$ git clone --branch <tag> --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

Once the extension is installed, it's time to configure it. Here's how:

In your Adobe Commerce (Magento) Admin Panel:

Go to: Stores → Configuration → Services → Ideal Postcodes

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

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

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)

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

You can also adjust additional settings to suit your store's specific needs.

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.

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

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 support@ideal-postcodes.co.uk.