Using Postcode Anywhere in a .NET site is straightforward. This step-by-step guide uses the ByFreeText method to find postcodes and addresses. The results are shown in a listbox which the user can then select from. Once the user selects a property, the FetchAddress method is used to get the fully formatted address which we then write into the label.

Before starting the tutorial, you need to build the basic project. The instructions for this are as follows:

• Create a new web project
• Create a text box and call it "txtFind"
• Create a button to the right of the text box, call it "btnFind" and change the text property to "Find"
• Below the text box and button, add a listbox and call it "lstProperties"
• Set the AutoPostback property of the list box to "True"
• Below the list box, create a label and call it "lblAddress"

Now you're ready to start making this work with Postcode Anywhere!

Adding a web reference instructs .NET that you are going to use a web service. Visual Studio connects to our servers and gets information about the services and makes them available to you.

• In the Solution Explorer in VS.NET, right click on project name and select "Add web reference..."

• In the URL text box, enter "http://services.postcodeanywhere.co.uk/uk/lookup.asmx" and click on the "Go" button
• In the Web Reference textbox, replace "uk.co.postcodeanywhere.services" with "PostcodeAnywhere"
• Click on the "Add Reference" button to complete the operation

When the user clicks on the Find button, we want to use the Postcode Anywhere web service to run a query and put the results into the list box.

To do this, we use the ByFreeText method. We need to provide the free text string (which we'll take from the text box) and an account code (from registration) and license key. If you don't have a license key yet, just click on "Set up Postcode Anywhere" in "My Account" and follow the steps to create a web service license key.

• Double click on the button to enter the code view for the page
• In the event handler code, enter this code which will run the query against the web service

Dim objLookup As New PostcodeAnywhere.LookupUK
Dim objInterimResults As PostcodeAnywhere.InterimResults
Dim objInterimResult As PostcodeAnywhere.InterimResult

'Make the request
objInterimResults = objLookup.ByFreeText(txtFind.Text, "aaaaa11111", _
   "aa11-aa11-aa11-aa11", "")

'Tidy up
objLookup.Dispose()

• That's all you need to do to get the results back from Postcode Anywhere! However we need to do a bit more to display the results to the user
• After the code we've already put in, we need something else to copy the results into the list box

'Copy the results into the list box
If objInterimResults.IsError Then

    'Write the error message to the address label
    lblAddress.Text = objInterimResults.ErrorMessage

Else

    'Clear the items in the list
    lstProperties.Items.Clear()

    'Add the new items to the list
    If Not objInterimResults.Results Is Nothing Then
        For Each objInterimResult In objInterimResults.Results
           lstProperties.Items.Add(new _
                ListItem(objInterimResult.Description , objInterimResult.Id))
        Next
    End If

End If

It's worth pointing out a few things here. First of all, the results are returned in the InterimResults structure. This has a property IsError which indicates whether there was a problem and another, ErrorMessage which indicates what happened.

As long as things have all gone well, we just copy the items from the Results list. If there are no items, this may be Nothing so we also need a test for that.

So far we've listed the matching items in the list box. Now we want to get the full address when the user selects an item in the list.

To do this, we use the FetchAddress method. We need to provide the id of the address to get (which we'll take from the selected item in the list box) and some other parameters which tell the service what information to return.

• Double click on the list box to enter the code view for the page
• In the event handler code, enter the following code which will run the query against the web service

Dim objLookup As New PostcodeAnywhere.LookupUK
Dim objAddressResults As PostcodeAnywhere.AddressResults
Dim objAddress As PostcodeAnywhere.Address

'Make the request
objAddressResults = objLookup.FetchAddress(lstProperties.SelectedValue, _
   PostcodeAnywhere.enLanguage.enLanguageEnglish, _
   PostcodeAnywhere.enContentType.enContentStandardAddress, _
   "aaaaa11111", "aa11-aa11-aa11-aa11", "")

'Tidy up
objLookup.Dispose()

• Now we've got the address it's just a case of copying it to the label
• We will also add in a bit of error handling as before

'Get the address
If objAddressResults.IsError Then

    'Write the error message to the address label
    lblAddress.Text = objAddressResults.ErrorMessage

Else

    'Get the address
    objAddress = objAddressResults.Results(0)

    'Write the label
    lblAddress.Text = ""
    lblAddress.Text &= "<br>" & objAddress.OrganisationName
    lblAddress.Text &= "<br>" & objAddress.Line1
    lblAddress.Text &= "<br>" & objAddress.Line2
    lblAddress.Text &= "<br>" & objAddress.Line3
    lblAddress.Text &= "<br>" & objAddress.PostTown
    lblAddress.Text &= "<br>" & objAddress.Postcode

End If

You should now have your very own .NET address finding application. Don't forget you can download our version of the code from the top of this page if you've experienced any problems.