SimplyCompleteAI Address Finder

“Search as you type” uses AI to find the address based on users input.

Easily Added by Anyone - The video below demonstrates how SimplyCompleteAI Address Finder can be easily added to almost any Web Site or Web App by adding a simple line of code. The AI-assisted Address Finder can be easily Setup and Styled with our "Page Assist" wizard as shown in the video.

Experienced Web Developers - For those with the skills and demand, once set up (via "Page Assist"), the site-specific Address Finder code can be downloaded from your API link. The JavaScript class can be built into your specific page/application build. More about the SimplyCompleteAI Class


Demonstration/Tutorial Video

   SimplyCompleteAI Address Finder for any WebSite
  0:00 Address Finder Search Demo
  1:53 How to add to the website
  3:30 Add code to your page
  4:00 The "Page Assist" Wizard
  5:50 How to Change the Style
  5:15 Mapping form fields to PAF Address Lines
  6:10 GeoLocation and Distance from home

SimplyCompleteAI Tutorial

The following example of how to add in minutes Address Finder to your website or web app follows the video at the top of the page.

Step 1 – Try our Address Finder Demo

We have a full Address Finder demo restricted to 15 searches per day, which shows the code in action, with search from the Dedicated Search Field and from the First Line of Address in a form. Which is discussed in the tutorial below.

Try Demo Address Finder Disussed in this page

Step 2 – Open a trial account and get the API Key

The API key identifies your account; under the online account 'SimplyCompleteAI' tab, you can restrict your key to work only from sites of defined origin.

Open Trial Account

Step 3 - Create Page Assist Definition

Under the 'SimplyCompleteAI' tab, press Add to your Web Page.

SimplyCompleteAI tab
'SimplyCompleteAI' tab to add SimplyCompleteAI definitions

Give a name tells you what this is. Such as "Checkout", "Contact Form" or "Main Address".

Age debt function
Set Search Options

Press Next

Set Address Finder Search Options
Set Address Finder Search Options

Set Search Options and here we can specify a Origin Filter to make sure no one else uses your API Key. We suggest you leave this blank until you have everything running. Then apply a filter.

Press Next

HTML to add to your page
HTML to add to your page.

Step 4 - Add to your web page

Next press Copy to copy the line of code. Add this line to any part of <head> or <body> section of the web page.
Best at the bottom of <body> section if possible, then only runs after everything is loaded.

Download this Example Form used in this tutorial

In the example form, we have two main address sections and two completely different Address Finder form layouts, which shows SimplyCompleteAI's flexibility.

Example 1 - Search in Dedicated Search Field

Here are the text inputs without formatting HTML:

 Address Finder in Dedicated Search Field
Address Finder in Dedicated Search Field

  Example 1 - Search in Dedicated Search Field   
         <input type="text" class="form-control " id="dedicatedSearchField" autocomplete="off">
   <textarea class="form-control" id="wholeaddress" rows="11"></textarea><br>
   <input type="text" class="form-control" id="geoposition" >
   <input type="text" class="form-control" id="geodistance" >

Where 'dedicatedSearchField' is the search text field, to enable the Address Finder, to search from.

Address Finder in First Line of Address
Address Finder in First Line of Address

Example 2 - Search in First Line of Address

Here the address finder is active or the first line of the Address in the form:

  Example 2 - Search in First Line of Address   
         <input type="text" class="form-control" id="organisation" >
   <input type="text" class="form-control " id="line1" >
   <input type="text" class="form-control" id="line2" >
   <input type="text" class="form-control" id="line3" >
   <input type="text" class="form-control" id="town" >
   <input type="text" class="form-control" id="county" >
   <input type="text" class="form-control" id="postcode" >
   <input type="text" class="form-control" id="country" >

Where organisation is the search text field, to enable the Address Finder, to search from. After search it will contain the address organisation after the search.

These two search fields are styled with the simplycomplete class; the wizard allows them to be styled, but they can be overridden. The style and placement text denotes to the user they are for Address Finder fields. More information

Next we add the line of code you copied from the 'SimplyCompleteAI' tab when we created the SimplyCompleteAI definition in your online account.

  Script line added to page   
         <script type='text/javascript'
   src=' KEY'>
   </script >


Step 5 - Upload Page Structure

After adding the line your your web page. Refresh the web page, and you should see a small button appear at the bottom right of the page:

Upload Page Structure Button
Upload Page Structure Button

Press the 1 Upload Page Structure button on your page to read your page structure. This will send all web field IDs to Page Assist. If you have many, type a value into the field you are interested in mapping to search. Page Assist will show these values against the mapping selection in the wizard.

 All Page Assist Buttons visible after Structure Upload
All Page Assist Buttons visible after Structure Upload

Step 6 - Edit Mappings and style

Then press the 2 Open Page Assist button to edit the mappings. This will open the Page Assist page:

Page Assist Name, Search Options and Security
Page Assist Name, Search Options and Security

The first tab offers many of the settings you see in the online account

The second tab "Style" allows the basic style of the search fields and list:

Style the Address Finder list and search field
Style the Address Finder list and search field

Next, we can move on to mapping your fields to the Daily Updated Simply Postcode PAF Address Data. In this case from a dedicated search field:

Mapping Example 1 to web fields
Mapping Example 1 to web fields

Here we have written in the wholeaddress field organisation[NL]line1[NL]line2[NL]line3[NL]town[NL]postcode[NL]country which puts new line between each address field. We can also have the addres comma delimited by using organisation[,]line1[,]line2[,]line3[,]town[,]county[,]postcode[,]country.

And, in our second example, from the first line of the address.

Mapping Example 2 to web fields
Mapping Example 2 to web fields

Now press the green Save button and go back to your web page and press the 3 Refresh Page button. We should now have styled the designed search fields, with placemenet text to tell the user they are Address Finder search fields:

After Page refresh SimplyCompleteAI is now activate
After Page refresh SimplyCompleteAI is now activate

Step 7 - Test and Refine

Now Test, Edit, Save, and Refine your mappings.

Set Origin Filter

To protect your API key from being used on someone else's website, set the origin filter in your online account under the "SimplyCompleteAI" tab or in the "Page Assist" settings.

Step 8 - Turn off Page Assist "Edit Mode"

Finally, turn off "Edit Mode" at the top right of the Page Assist page. Hit the big red button Exit Edit Mode.

Turn off "Edit Mode" top Right
Turn off "Edit Mode" top Right

Address Finder Finished

To re-enable it, you need to go to the 'SimplyCompleteAI' tab in your online account and press Edit to switch back on in the second page of the wizard.

 Turn "Edit Mode" back on under the SimplyCompleteAI tab
Turn "Edit Mode" back on under the SimplyCompleteAI tab

Optional : Address Finder Advanced options

The Address Finder Advanced options page allows:

Age debt function
Turn off "Edit Mode"

Option Description
Home Location This can be a valid formatted postcode or "Lat,long". In our example it is "SW1A0AA" which is Big Ben. But could be "52.659857,0.1617" which would be slightly faster.
Home Location Field Or get Home Location from a field on the form.
Customer License ID Field This enables the Simply Postcode reseller to set up SimplyCompleteAI on the website or app using one API key common to all customers. Then, populate each customer ID in a hidden form field to charge the reseller's end customer. As part of the Royal Mail Terms and Conditions, each end customer should have their own account.
After filling in address call JavaScript Function Enter "DoOtherThings();" to call you own function after address search is complete. Use with care else will cause a error.

Optional : SimplyCompleteAI Address Finder Styles

The Page Assist wizard allows us to quickly setup and apply styling. Should you want to define your own styles, tick the "Manual Style the Page with Stylesheet" option at the bottom of the "style" page of the wizard. Then define:

SimplyCompleteAI styles
SimplyCompleteAI styles

          /* SimplyCompleteAI styles for search box */

/* Search box */
.simplycomplete {
   width: 100%;
   padding: 10px;
   font-size: 16px;background-color: #e3f2fd;
   border: 3px solid #ced4da;

.simplycomplete::placeholder {
   color: #afaeae;
   font-style: italic;

/* Search List */
.simplysuggestions {
   font-family: Arial, Helvetica, sans-serif;
   font-size: 16px;
   line-height: 1.5em;
   border: 1px solid #ccc;
   max-height: 450px;
   overflow-y: auto;
   position: absolute;
   background: white;
   width: calc(100% - 2px);
   display: none;
   z-index: 3;
        .simplysuggestions b {
   font-size: 1.1em;
   font-weight: 700;

/* Search List Item */
.simplysuggestion-item {
   padding: 10px;
   cursor: pointer;

.simplysuggestion-item.highlighted {
   background-color: #eee;

/* Search Instructions in first line */
.simplyinstructions {
   color: #e97c17;
   cursor: default;
   font-style: italic;
   font-size: 0.9em;
   background-color: #f8f9fa !important;

/* Search Instructions Tab to complete */
   font-weight: 400;
   color: #0b0ff5 !important;


Optional : Faster Page Loading

For those who wish to include the SimplyCompleteAI code either within a web build or hosted on their own server, once set up, you can download the SimplyCompleteAI code to include in your web offering.

Get Code

To get a minified version we call KEY"" or an unminified version " KEY".

How the code works

Obviously the unminified version is easier to understand. Here is a brief outline of the functions:


Firstly, we define a class called SimplyComplete, which contains all the functionality. Then, when the DOM is loaded, we initialise this class with the API key and other values set by "Page Assist". The "Page Assist" settings also alter the generated code in order to make it as efficient and short as possible.

Setup Search

The class initialiser then calls .setupInputs() to style and add hooks to the Address Finder Fields from the list specified settings. This adds class='simplycomplete' to each designated search box, and if style is set by "Page Assist" then it appends the 'simplycomplete' style configuration to the page.

Write back found Address

When an address is selected by the user of the Web Address Finder, the .PAD(details, inputid) function is passed the selected address details (listed in the next section) to populate to populate the form fields. inputid is a number corresponding to the field having searched from.


Data Returned by SimplyCompleteAI Address Finder

After the address is selected by the user, the Web Address Finder returns the following data.

Data Returned by Address Finder

For 99% of our customers, they only need the following core address data:

Name Description
organisation Organisation if a company or organisation.
line1 Line 1 of address, always contains data.
line2 Line 2 of address, not always filled in.
line3 ★ Line 3 of address, not always filled in.
town Town. Always filled in.
county ★ County, not always filled in.
postcode Formated Postcode.
If the Taxi Locations option is ON, then Trains and Bus Stations will return UNKOWN since they have no Postcode.
'Taxi Locations' are intended to get GeoLocation for booking Taxis.
country England, Scotland, Wales...

★ - Not required by the Royal Mail to send letters and parcels.

License Status

The current License status, or error is returned:

Name Description
error BOOLEAN : true if error, else false
licenseStatus Status of license, or Error if error. Not shown if public site.


The GeoLocation is returned if known within 100 meters. SimplyCompleteAI will also return straight line distance if a home location is specified (Lat/Long or valid postcode):

Name Description
geodistanceinkm Distance from homelocation in km. homelocation is either set in SimplyComplete Class or under the 'SimplyCompleteAI' tab in your online account.
geodistanceinmiles Distance from homelocation in miles. homelocation is either set in SimplyComplete Class or under the 'SimplyCompleteAI' tab in your online account.
geoposition 'Lat,Long' of Address within 100m
geolatitude Lat within 100m
geolongitude Long of Address within 100m

Additional Data

The Simply Postcode PAF database contains some additional data returned as follows:

Name Description
rawpostcode Postcode as stroed in PAF. 7 chars long
deliverypointsuffix This code can be added to the postcode to give a unique reference to each Delivery Point (letterbox) in a Postcode. Although the UDPRN number is a better source of a unique ID.
nohouseholds Number of house holds at this postcode address
smallorg Y = Small Organisation
pobox PO Box number if PO Box address
mailsortcode The Royal Mail offer discount if mail is sorted by this code
udprn Unique 8 digit code assigned to each addressable property (Delivery Point).
Gives the unique portion of the address record. Can be 2 lines.
propertyNo Property Number, if an address is a simple number in a street.
propertyName Property Name. This can contain two lines separated by "," A number like "1-3","3A" are treated as names (see below)
streetName Name of street.

  Additional Data Example   
    Postcode SW11 1QG returns address:

Flat 6
Carrington Court
21 Limburg Road
SW11 1QG
United Kingdom

unique1 returns "Flat 6"
unique2 returns "Carrington Court"
PropertyNo returns "21"
PropertyName returns "Carrington Court"
StreetName returns "Limburg Road"