Client Side Integration, ePostcode

Developers

Client Side Integration

Getting Started with Client Side Javascript

Using client side javascript is the simplest way of integrating ePostcode into existing or new build websites.

To get you started, we suggest you download the following zip file:

Client Side Javascript Downloads
.Zip File containing html file	download

Once you have unzipped the files simply double-click the DirectAccess.htm file to open it in a browser and press the 'Find Address' button.

You should receive the following Error Message 'Invalid Account' in the drop down listbox.
This is because the ePostcode AccountName and GUID are not using your own Account Details.

If you have not already signed-up for an account click here Sign-Up Now.
You will receive your Access Codes by email and you will receive 50 free credits.

When you have your Access Codes ready, open the DirectAccess.htm file in 'Source View' by opening it in a common text editor like Notepad.

You will see 2 lines near the top that look like the lines below:

Replace the XXXXXXXX value with your ePostcode AccountName.
Replace the XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX value with your ePostcode GUID.

Save and Close the DirectAccess.htm.

Now, reopen the DirectAccess.htm file in a browser, enter a Postcode in the 'Search Postcode' input box and press the 'Find Address' button.

If the Postcode is valid and you have entered your ePostcode Account Details correctly you will receive a list of Addresses for that Postcode. This functionality uses the SearchMulti function of the ePostcode web service.

Now scroll the list and select the address you want by clicking on it. Press the 'Get Selected Address' button. You should now be shown the Full Postal Address Details for that address. This functionality uses the GetAddress function of the ePostcode web service and you have just used your first credit by returning the address details.

It's that simple, you now have access to a client-side Address Search. Every time you press the 'Get Selected Address'' button on the page your Credit Limit will be decremented by 1 Credit.

So, how does it work?

If you inspect the 'Source View' of the DirectAccess.htm file in Notepad, you will see the following 2 lines

SSL Note: If you are using Secure Socket Layer (SSL) pages please replace the 2 lines above with the following:

These are the Javascript files that do all the hard work by calling the SearchMulti and GetAddress method of the eSortcode web service and returning the details to the DirectAccess.htm file.

The ePostcodeDemoFieldsSSL.js Javascript file contains 2 procedures called 'GetAddressList' and 'GetAddress' which are called when you press the 'Find Address' and 'Get Selected Address' buttons respectively on the page. See below.

The 'GetAddressList' and 'GetAddress' procedures both use the Values from the 4 hidden fields shown below

The 'GetAddressList' also uses the Values entered by the user for Search Postcode, Search Company, Search Street, Search Locality, Search Town and SearchNumber shown below:

<tr>
   <td>Search Postcode</td>
   <td><input name="epcSearchPostcode" type="text" id="epcSearchPostcode"></td>
</tr>
<tr>
   <td>Search Company</td>
   <td><input name="epcSearchCompany" type="text" id="epcSearchCompany"></td>
</tr>
<tr>
   <td>Search Street</td>
   <td><input name="epcSearchStreet" type="text" id="epcSearchStreet"></td>
</tr>
<tr>
   <td>Search Locality</td>
   <td><input name="epcSearchLocality" type="text" id="epcSearchLocality"></td>
</tr>
<tr>
   <td>Search Town</td>
   <td><input name="epcSearchTownOrCity" type="text" id="epcSearchTownOrCity"></td>
</tr>
<tr>
   <td>Search Number</td>
   <td><input name="epcSearchNumber" type="text" id="epcSearchNumber"></td>
</tr>

The 'GetAddress' also uses the Value Field of the Selected Index of the select box (This value is the AbsRecNum value which is a unique id that every address has and is set when the 'Find Address' button is pressed) shown below:

So, when the 'Find Address' button is pressed the javascript file calls the SearchMulti function of the epostcode webservice and populates the dropdown list with the returned list addresses and their corresponding Unique IDs (assuming valid details).

And, when the 'Get Selected Address' button is pressed the javascript file calls the GetAddress function of the epostcode webservice and populates the remaining text boxes with the selected Address Details (assuming valid details).

How do I integrate this into my site?

It should be very easy, the simplest way is to copy and paste the html between the <form></form> tags into your own page. You can then format and position the fields as you wish.

You MUST include the reference to the Javascript file in your page and the following input fields also MUST be present (but not necessarily visible):

NB: Do NOT change the name of any of the input or return fields as the Javascript file requires them to have specific names in order for it to work.

Fields that must exist:

epcServiceName
epcAccountName
epcGUID
epcIPAddress
epcSearchPostcode
epcSearchCompany
epcSearchStreet
epcSearchLocality
epcSearchTownOrCity
epcSearchNumber
epcAddressList
epcFindAddresses
epcGetAddress

You do not necessarily have to include all of the return fields because the javascript file ignores them if they don't exist.

Return Fields:

epcCompany
epcDepartmentName
epcSubBuildingName
epcBuildingName
epcNumber
epcDependentStreet
epcStreet
epcDoubleDependentLocality
epcLocality
epcTownOrCity
epcCounty
epcPostcode
epcAddressLine1
epcAddressLine2
epcAddressLine3
epcAddressLine4
epcAddressLine5
epcGridEasting
epcGridNorthing
epcPostOfficeBox
epcUserCategory
epcIsError
epcErrorMessage
epcAbsRecNum

Remember to always include the reference to the javascript file and all of the input fields (do not rename these) and remember to enter your Access Codes. If you download your own local copies of the javascript files, we reccommend that you DO NOT make any changes to the ePostcodeProxy.js file as this will probably break the code.

For a full technical description of the ePostcode web service and the 3 methods click on the following link Web Service Described

If you have any questions feel free to contact us at the following link Contact Us.