The Autoaddress plugin is designed with an event-driven architecture, allowing you to enhance its functionality by subscribing to these events. This document serves as a comprehensive guide for the events within the Autoaddress plugin.

Event driven plugin

An event-driven plugin is one that relies on events or triggers to communicate and execute specific functions. The Autoaddress plugin responds to various events that occur during its lifecycle, and by understanding and utilizing these events, you can extend and customize the behavior of the plugin to suit your specific requirements. 

Subscribing to events

The below code snippet demonstrates the usage of callback events within the Autoaddress control.

In this code:

Autoaddress is an object representing the Autoaddress plugin, and you initialize it with configuration options.

apiKey should be replaced with your actual API key from the Account Center.

elementId specifies the ID of the HTML element where the Autoaddress plugin will be rendered.

The code also defines several sample callback events:

onPostInit: This event is triggered after the plugin is initialized. You can add custom logic within the callback function to perform actions once the plugin is ready.

onAddressResult: This event is triggered by either the user selecting an address from autocomplete options or if the user opted into format entered address changes on the Autoaddress form. The latter is only available if your integration is AutoaddressForm.

onAddressFormChange: This event is triggered when the user chooses to enter the address manually instead of using autocomplete. You can define how to handle this user action.

<script type="text/javascript">
var aa = Autoaddress({
  key: "YOUR_KEY",
  elementId: "aa-control",    
  onPostInit: function(token) {
    // This callback is triggered after the plugin is initialized.
    // You can add custom logic here.
  onAddressResult: function(result) {
    // This callback is triggered when the user selects an address from autocomplete api.
    // Also additionally gets triggered if you called `aa.triggerFormatEnteredAddress()` which will include form changes.
    const result = await aa.getAddressResult();
    const { lines, city, region, postcode, country } = result?.address;
    const addressLabel = result?.address?.label;
    // Sample extracting data attributes (if available)
    const { location = {} } = result?.data;
    const { latitude, longitude } = location;
  onAddressFormChange: function(address) {
    // This callback is triggered when the user makes manual changes to the Autoaddress form.
    // For example trigger a call to our FormatEnteredAddress api on form change to keep address result in sync with live changes.
    // This will also invoke the onAddressResult callback
  // Add more callback events as needed...


You can add more callback events to respond to various interactions and stages within the Autoaddress plugin. These callbacks allow you to tailor the behavior of the plugin to your specific requirements.

API Callbacks

Two generic callbacks, onPreAPI and onPostAPI are provided for when the javascript control interacts with the Autoaddress 3 API. These callbacks are typically used for debugging but can also be used to influence the behaviour of the Autoaddress control.

Note: Using the onPreAPI and on PostAPI callbacks to influence the behaviour of the Autoaddress control 

  Callback Event DescriptionData Passed
  onPreAPI(obj)Triggered before an Autoaddress 3 API call is made. 
If you return false from an onPreAPI callback, then the Autoaddress control will not invoke the API endpoint.
If you return any other value (or return nothing), then the API endpoint will be invoked as normal. Returning false from this callback is considered an advanced feature and should be used with extreme caution.

 An object containing two fields:-

  • type, a string defining the API endpoint to be called
  • params, an object containing the parameters that will be passed to the API endpoint.
  onPostAPI(obj)Triggered after an Autoaddress 3 API call is made. If you return an object from this callback, the control will continue as if that was the return value from the API. Returning an object from this callback is considered an advanced feature and should be used with extreme caution.The response object as returned by the API endpoint.

Search Lifecycle Callbacks

 Callback Event Description Data Passed
  onAddressResult(result)Triggers after the completion of a Lookup API call i.e. when an address has been selected, and optionally, it also includes FormatEnteredAddress API calls if they have been triggered.

If this is the case then the latest user entered address will be merged into the Lookup API result.
The full response data from Lookup API is now available to you. See here for a sample response.
  onSelectItem(link)Triggers when an autocomplete option is selectedLink generated for the Lookup API for selected item.

Control Display Callbacks

EventDescriptionData passed
onPostInit(token:string)Triggers after the javascript control has been initialized.Your API token to be used in subsequent API calls (optional)
onShowSearchBar()Triggers when search bar is to be shownNone
onHideSearchBar()Triggers when search bar is to be hiddenNone
onShowCustomerFields()Triggers when your existing address form is to be shown for example if you have passed a settings of customerFieldId.None


Triggers when your existing address form is to be hiddenNone

 User Action Callbacks

Event Description Data passed
onAddressFormChange(address:string[])Triggers when a manual change has been made to the Autoaddress form. Only triggered if your integrationType is "AutoaddressForm".Current value of address lines in the        Autoaddress form
  onSelectEnterAddressManually(address:string)Triggers when the "Enter address manually" option is chosen from a list of options.Current text from search box
onClickSearchButton(address:string)Triggers when the search button is clicked.Current text from search box
onClickInputField(address:string)Triggers when the autocomplete input field is     clicked on.Current text from search box
onSelectCountry(countryCode:string)Triggers when a country is selected from the Autoaddress form.Two-letter country code, which adheres to the ISO 3166-1 alpha-2 standard. For example, 'IE' represents Ireland, 'CA' represents Canada, and 'GB' represents the United Kingdom

Error Callbacks

EventDescriptionData Passed
onError(error)Triggers when an error occurs within plugin setup or http eventsError object key/value pair consisting of code error and message