Implementing the Inline Address Finder

How It Works

The inline service is an extension of our standard XML services. However, instead of returning XML formatted data, it actually returns JavaScript which is then executed by the browser. Because browsers can load JavaScript dynamically, it's possible to access any of the Postcode Anywhere services from a simple HTML page without the need for postbacks or server coding.

Actually using the Inline service is very simple, and entirely consistent with the other Postcode Anywhere services. Basically, you build a URL containing your account code, license key and information about what to find, then get the browser to make the request.

Unique to the Inline service though, you also provide the name of the function to be called when the results are present. This "callback" function is executed automatically when the browser completes the request.

This tutorial takes you step by step though setting up the JavaScript Inline service on a simple HTML page. It only takes a few minutes and you can see how powerful it really is!

Preparation

Before starting this tutorial, we need to create a simple HTML page which we will add the inline code to. In this example we've put postcode and building fields at the top of the page so that the customer doesn't begin entering their address before they see the auto complete facility. We have also added a search button.

You will also need a web service key (just go through the setup wizard in My Account to get one if you don't already).

<form method=post>
 
   <table>
      <tr>
         <td>Postcode</td>
         <td><input type=text name=postcode id=postcode size=10></td>
      </tr>
      <tr>
         <td>Building</td>
         <td>
            <input type=text name=building id=building size=5> 
            <input type=button value="Find"> 
         </td>
      </tr>
      <tr>
         <td>Company name</td>
         <td><input type=text name=company id=company size=40></td>
      </tr>
      <tr>
         <td>Line 1</td>
         <td><input type=text name=line1 id=line1 size=40></td>
      </tr>
      <tr>
         <td>Line 2</td>
         <td><input type=text name=line2 id=line2 size=40></td>
      </tr>
      <tr>
         <td>Line 3</td>
         <td><input type=text name=line3 id=line3 size=40></td>
      </tr>
      <tr>
         <td>Town</td>
         <td><input type=text name=town id=town size=40></td>
      </tr>
      <tr>
         <td>County</td>
         <td><input type=text name=county id=county size=40></td>
      </tr>
   </table>
 
</form>

Step 1: Add the code to request the data

The first step is to add the inline code which actually makes the request to Postcode Anywhere. We can get this code direct from the RetrieveByPostcodeAndBuilding documentation.

function PostcodeAnywhere_Interactive_RetrieveByPostcodeAndBuilding_v1_10Begin(Key, Postcode, Building, UserName)
   {
      var scriptTag = document.getElementById("PCA38d38252878f434581f85b249661cd94");
      var headTag = document.getElementsByTagName("head").item(0);
      var strUrl = "";

      //Build the url
      strUrl = "http://services.postcodeanywhere.co.uk/PostcodeAnywhere/Interactive/RetrieveByPostcodeAndBuilding/v1.10/json.ws?";
      strUrl += "&Key=" + escape(Key);
      strUrl += "&Postcode=" + escape(Postcode);
      strUrl += "&Building=" + escape(Building);
      strUrl += "&UserName=" + escape(UserName);
      strUrl += "&CallbackFunction=PostcodeAnywhere_Interactive_RetrieveByPostcodeAndBuilding_v1_10End";

      //Make the request
      if (scriptTag) 
         {
            try
              {
                  headTag.removeChild(scriptTag);
              }
            catch (e)
              {
                  //Ignore
              }
         }
      scriptTag = document.createElement("script");
      scriptTag.src = strUrl
      scriptTag.type = "text/javascript";
      scriptTag.id = "PCA38d38252878f434581f85b249661cd94";
      headTag.appendChild(scriptTag);
   }

function PostcodeAnywhere_Interactive_RetrieveByPostcodeAndBuilding_v1_10End(response)
   {
      //Test for an error
      if (response.length==1 && typeof(response[0].Error) != 'undefined')
         {
            //Show the error message
            alert(response[0].Description);
         }
      else
         {
            //Check if there were any items found
            if (response.length==0)
               {
                  alert("Sorry, no matching items found");
               }
            else
               {
                  //PUT YOUR CODE HERE
                  //FYI: The output is an array of key value pairs (e.g. response[0].Udprn), the keys being:
                  //Udprn
                  //Company
                  //Department
                  //Line1
                  //Line2
                  //Line3
                  //Line4
                  //Line5
                  //PostTown
                  //County
                  //Postcode
                  //Mailsort
                  //Barcode
                  //Type
                  //DeliveryPointSuffix
                  //SubBuilding
                  //BuildingName
                  //BuildingNumber
                  //PrimaryStreet
                  //SecondaryStreet
                  //DoubleDependentLocality
                  //DependentLocality
                  //PoBox
                  //CountryName
               }
         }
   }

Step 2: Call the method from the button

Now we need to add an OnClick expression to the button to start the search:

<input type=button value="Find" 
   onclick="Javascript: PostcodeAnywhere_Interactive_RetrieveByPostcodeAndBuilding_v1_10Begin
      ('AA11-AA11-AA11-AA11',
       document.getElementById('postcode').value, 
       document.getElementById('building').value,
       ''
      )"> 

Obviously, you will need to put your own key in there too.

Step 3: Dealing with the response

So far we've copied the code to make the request and hooked it onto our form but how do we get the response? This is where things are slightly different to what you might expect.

To make the request, we call PostcodeAnywhere_Interactive_RetrieveByPostcodeAndBuilding_v1_10Begin (). This completes almost right away as the request to our servers happens in the background. When the results have been downloaded, PostcodeAnywhere_Interactive_RetrieveByPostcodeAndBuilding_v1_10End () gets called automatically so it's here that we need to handle the response.

In this example, we want to copy the address into textboxes on the form so we update the PostcodeAnywhere_Interactive_RetrieveByPostcodeAndBuilding_v1_10End () function with some extra lines:

function PostcodeAnywhere_Interactive_RetrieveByPostcodeAndBuilding_v1_10End(response)
   {
      //Test for an error
      if (response.length==1 && typeof(response[0].Error) != 'undefined')
         {
            //Show the error message
            alert(response[0].Description);
         }
      else
         {
            //Check if there were any items found
            if (response.length==0)
               {
                  alert("Sorry, no matching items found");
               }
            else
               {
	document.getElementById("company").value= response[0].Company;
	document.getElementById("line1").value= response[0].Line1;
	document.getElementById("line2").value= response[0].Line2;
	document.getElementById("line3").value= response[0].Line3;
	document.getElementById("town").value= response[0].PostTown;
	document.getElementById("county").value= response[0].County;
	document.getElementById("postcode").value= response[0].Postcode;

               }
         }
   }

The actual data is supplied in a table. Where no items are found, the response will be empty (although all endpoints specify the columns). If an error occurs, the response will not follow this format. Instead the response will be an error table.

Step 4: All Done!

That really is it! As you can see, the process is very simple and most of the nasty code is automatically generated for you. You can access all the Postcode Anywhere core services using this mechanism and better still, it makes the pages look really slick!