Virtuemart getAddress.io Postcode Lookup
United Kingdom Postcode lookup for Virtuemart.
This plugin enables your customers to complete their billing/shipping address by entering their postcode and selecting their address from the options given.
It utilises getAddress.io API (https://getaddress.io) to do the lookup cross referencing Ordnance Survey's complete list of uk postcodes (code point open) with the latest property sales, council tax register, companies house data and over twenty other data sources to create near complete address database.
An API key is required for the integration to work, and the integration only appears when the customer has selected United Kingdom for their country. Will also work if Jersey or Guernsey selected
It can optionally be turned off for the shipping or billing addresses, and it can be configured to send an email notification to a nominated address if the getAddress.io API key hits its usage limit.
- Joomla Plugin
- Product Type:
- Released On:
- 20 April 2018
- Updated On:
- 31 January 2024
- J3 J4 VM3 VM4
You can download the latest installation packages from our site's download page for getAddress.io Postcode plugin. Please check the compatibility section to find the version of getAddress.io Postcode plugin compatible with your Joomla!, VirtueMart and PHP versions.
It is a Virtuemart! Userfield Plugin and can be installed directly through Joomla! Extension Installer. It can also be used to upgrade getAddress.io Postcode plugin; just install it without uninstalling the previous release.
You can uninstall the component just like any other Joomla! plugin. In your site's back-end, just go to Extensions Manager, search for 'GetAddress IO', select 'GetAddress IO User Field' and click on Uninstall. This will completely remove getAddress.io Postcode plugin from your site.
Once installed and enabled, you need to go to the Virtuemart -> Plugins -> page and search for GetAddress. Enable the plugin, and click on the plugin to edit its settings. You can enter your API key and set your other options here. Remember to turn on Enable for Billing Address and Enable for Shipping Address if required.
Next go to Virtuemart -> Configuration -> Shopper fields. Add two new plugin fields (choose field type = 'GetAddress IO User Field') billing_postcode and shipping_postcode. If only using for billing you do not need to add shipping_postcode.
These field are in addition to your existing postcode field. Make sure these are set to not required.
Now re-order the fields so virtuemart_country_id, billing_postcode and shipping_postcode are after last_name and before the standard address fields.
Default Country to United Kingdom
Go to the Country list and find the relevant virtuemart_country_id for United Kingdom normally it is 222. Now go to the Shopper Field list and for virtuemart_country_id enter 222 against Default. It is that easy.
The following plugin settings are available in the backend.
- GetAddress API Key Please provide your GetAddress API Key.
- Allow Browser Autocomplete If yes, the browser will attempt to populate if user selects autocomplete.
- Use Placeholder If yes, placeholder will be used for input.
- Use Label If yes, label will be used for input.
- Postcode field Select Virtuemart Postcode shopper field
- Fields to Hide Fields to hiden when UK selected. If nothing entered, default will be used 'address_1', 'address_2', 'city', 'state' and 'zip'
- Native UK Countries Select the native UK country or countries to perform postcode lookup for your shop. i.e. United Kingdom, Jersey or Guernsey
- Enable for Billing Address If yes, add the lookup field to the Billing Address section of the checkout.
- Enable for Shipping Address If yes, add the lookup field to the Shipping Address section of the checkout.
- Hide Address Fields Hide address fields until a lookup is performed and an address is selected - does not hide fields if an address is already present!
- Allow Manual Entry Allow customers to chose to enter their address manually, when 'Hide Address Fields' is turned on - think very carefully before turning this off!
- Email when Usage Limit Hit If populated then this email address is sent a warning when API usage is high. Only one email will be sent in a day.
getAddress.io offers several test postcodes that can be entered to test that it is working without impacting on your usage limits. These are:
XX2 00X - Returns a 'successful' response 200. Your request was successful.
XX4 04X - Returns 'not found' error 404. No addresses could be found for this postcode.
XX4 00X - Returns 'bad request' error 400. Your postcode is not valid.
XX4 01X - Returns 'forbidden' error 401. Your api-key is not valid.
XX4 29X - Returns 'too many requests' error 429. You have made more requests than your allowed limit.
XX5 00X - Returns 'server error' error 500. Server error, you should never see this.
See the getAddress.io documentation (https://getaddress.io/Documentation) for more details.
For developers, I've included a few settings that you can use to customise certain aspects of the plugin. These are:
Copy plugins/vmuserfield/getaddressio/tmpl/text.php to your template directory templates/your_template/html/plg_vmuserfield_getaddressio/, and customize how you wish.
In settings alter whether to display Label, placeholder etc. For languages, edit in language overrides, the text and error message that will be displayed to the user.
PLG_VMUSERFIELD_GETADDRESSIO_FIND_ADDRESS - the text shown on the Find Address buttons (default: Find Address)
PLG_VMUSERFIELD_GETADDRESSIO_FIND_ADDRESS_SEARCHING - the text shown when the Find Address button is selected (default: Searching...)
PLG_VMUSERFIELD_GETADDRESSIO_MANUAL_ADDRESS - the text shown for the "Enter an address manually" link (default: Enter an address manually)
Note: These texts are translateable, change in language overrides.
Edit in language overrides, the error message that will be displayed to the user.
PLG_VMUSERFIELD_GETADDRESSIO_ERROR_INVALID_POSTCODE - api_error_400 - shown when the postcode supplied is invalid/empty
PLG_VMUSERFIELD_GETADDRESSIO_ERROR_INVALID_API_KEY - api_error_401 - shown when the API key provided in the settings is invalid
PLG_VMUSERFIELD_GETADDRESSIO_ERROR_NO_ADDRESSES_FOR_POSTCODE - api_error_404 - shown when no addresses were found for the supplied postcode
PLG_VMUSERFIELD_GETADDRESSIO_ERROR_LOOKUP_FAILED - api_error_429 - shown when the API key has hit its usage limit
PLG_VMUSERFIELD_GETADDRESSIO_ERROR_SERVER_ERROR - api_error_500 - shown when there is a server error at getAddress.io
Note: By default, the error messages are “customer friendly”, i.e. they don’t go into much detail about the cause of the error!
ersd-virtuemart-getaddress-io_billing_selector_row_class - changes the CSS class on the form-row that the billing address selector is placed into
ersd-virtuemart-getaddress-io_shipping_selector_row_class - changes the CSS class on the form-row that the shipping address selector is placed into
Over Usage Email Notification
In the plugin settings you can change the Over usage email recipient - change the recipient passed to mail function
Edit in language overrides, the over usage subject line.
PLG_VMUSERFIELD_GETADDRESSIO_ERROR_API_LIMIT_REACHED - change the subject line passed to mail function for the over-usage email