Skip to main content
SOAP API

SOAP API Postcode Lookup Walkthrough

Intended Audience

This walkthrough is aimed at developers who wish to utilise the Hopewiser SOAP web service with the Microsoft .NET Framework.

It assumes you have already imported our WSDL into your project. If you need help with importing a WSDL, start by following the .NET Postcode Sample Documentation (PDF). You can also download the .NET Postcode Sample Code .

These source code examples are written in Visual Basic.NET. The examples should be treated as a guide only; the intention is merely to show how to connect to the service, submit queries and manage responses. The general approach illustrated applies in principle to other languages.

Basics

How do I connect to the service

In order to use the service, you will need to create an Atlas object that contains your credentials.

Begin by creating a username token from your token username and token password:

Dim oUsernameToken As New HpwSoap.usernameTokenType
oUsernameToken.Username = My.Settings.username
oUsernameToken.Password = My.Settings.password

The above assumes you have stored your token username and token password values in the project settings.

Next, create a security object from your username token:

Dim oSecurity As New HpwSoap.securityType
oSecurity.UsernameToken = oUsernameToken

Now you can create an Atlas object and assign your credentials to it:

Dim oAtlas As New HpwSoap.soapaddrsvrInterfaceService
oAtlas.Security = oSecurity

How do I discover my available Master Address Files?

The service Status will list all the datasets you can use and tell you which one is your default.

Begin by creating an Atlas object as above, and then create a Status Request object:

' Set up the request
Dim oRequest As New HpwSoap.StatusRequest

Now you can call the Status method, passing in the Status Request object and storing the return value in a Status Response object:

' Do the lookup
Dim oResponse As HpwSoap.StatusResponse = oAtlas.Status(oRequest)

The Status Response object contains your default dataset and an array of alternate datasets that you can use, along with a status code and description.

' Default dataset
If Not oResponse.Default Is Nothing Then
  MsgBox(oResponse.Default.MAF.version & ", " & oResponse.Default.MAF.Value)
End If

' Alternate datasets
If Not oResponse.Alternate Is Nothing Then
  For Each oMafType In oResponse.Alternate
    MsgBox(oMafType.version & ", " & oMafType.Value)
  Next
End If

' Status
If oResponse.StatusCode > 0 Then
  MsgBox(oResponse.StatusDesc)
End If

If there is a problem, for example if the token username or token password is incorrect, an exception will be thrown. The exception message will contain information about the cause of the problem:

Try

  ... ' all of the code above

Catch ex As System.Exception
  MsgBox(ex.Message)
End Try

How do I look up a postcode?

Begin by creating an Atlas object as above, and then create a Postcode Lookup Request object that contains your postcode:

' Set up the request
Dim oRequest As New HpwSoap.PostcodeLookupRequest
oRequest.Postcode = txtPostcode.Text

The above assumes the postcode you want to look up has been typed into a text box named txtPostcode.

To look up this postcode against your default dataset and using the default options, call the Postcode Lookup method, passing in the Postcode Lookup Request object and storing the return value in a Postcode Lookup Response object:

' Do the lookup
Dim oResponse As HpwSoap.PostcodeLookupResponse = oAtlas.PostcodeLookup(oRequest)

The Postcode Lookup Response object contains an array of matching Address objects, along with a status code and description.

For Each oMatchType In oResponse.Match
  If Not oMatchType.Address Is Nothing Then
    Dim oAddress As HpwSoap.addressType = oMatchType.Address
    MsgBox(oAddress.Department & vbCrLf & _
      oAddress.Organisation & vbCrLf & _
      oAddress.Line1 & vbCrLf & _
      oAddress.Line2 & vbCrLf & _
      oAddress.Line3 & vbCrLf & _

...

      oAddress.Town & vbCrLf & _
      oAddress.County & vbCrLf & _
      oAddress.Postcode)
  End If
Next

' Status
If oResponse.StatusCode > 0 Then
  MsgBox(oResponse.StatusDesc)
End If

If you requested a Formatted Label (see below), the Postcode Lookup Response object will also contain an array of Formatted Label objects.

For Each oMatchType In oResponse.Match
  If Not oMatchType.FormattedLabel Is Nothing Then
    If (oMatchType.FormattedLabel.status = HpwSoap.statusString.ok) Or _
      (oMatchType.FormattedLabel.status = HpwSoap.statusString.split_element) Then
      Dim oLabel As HpwSoap.formattedLabelType = oMatchType.FormattedLabel
      MsgBox(oLabel.Line1 & vbCrLf & _
        oLabel.Line2 & vbCrLf & _
        oLabel.Line3 & vbCrLf & _
        oLabel.Line4 & vbCrLf & _
        oLabel.Line5 & vbCrLf & _

...

      )
    End If
  End If
Next

' Status
If oResponse.StatusCode > 0 Then
  MsgBox(oResponse.StatusDesc)
End If

You will most likely want to display the matching addresses in a list or a grid but here we are just displaying them in a message box for simplicity.

If there is a problem, for example if the token username or token password is incorrect, an exception will be thrown. The exception message will contain information about the cause of the problem:

Try

  ... ' all of the code above

Catch ex As System.Exception
  MsgBox(ex.Message)
End Try

Customisations

How do I customise what is returned?

You can create a Request Options object containing the settings you want, and then add this to the Postcode Lookup Request object that is passed into the Postcode Lookup method.

Dim oRequestOptions As New HpwSoap.postcodeLookupRequestOptionsType

oRequestOptions.AddressType = 1 ' 0=Address Fields, 1=Formatted Label
oRequestOptions.AddressTypeSpecified = True

oRequestOptions.MaxMatches = 400

... ' other options

oRequest.RequestOptions = oRequestOptions

For a full list of available options and their effects, please see the separate service documentation.

Some options, like Address Type above, require an additional Specified flag to be set to True for your setting to take effect.

How do I customise the formatted addresses that are returned?

If you used the Request Options to request a Formatted Label (as opposed to only individual address fields), you can customise the layout and the number of lines that the label will be formatted into.

You can create a Formatted Label Options object containing the settings you want, and then add this to the Postcode Lookup Request object that is passed into the Postcode Lookup method.

Dim oLabelOptions As New HpwSoap.formattedLabelOptionsType

oLabelOptions.LabelFormat = 0 ' 0=FixedTown, 1=FixedPostcode, 2=FreeFormat
oLabelOptions.LabelFormatSpecified = True

oLabelOptions.NumLines = 7

... ' other options

oRequest.FormattedLabelOptions = oLabelOptions

For a full list of available options and their effects, please see the separate service documentation.

Some options, like Label Format above, require an additional Specified flag to be set to True for your setting to take effect.

How do I look up against a different dataset?

You can specify a dataset in the MAF property of the Postcode Lookup Request object.

oRequest.MAF = "uk-rm-paf-internal"

The value can be the value of Default.MAF.Value or an oMafType.Value as returned in the Status Response object, above.

How do I get extra data?

Discovery

To discover what Extra Data is available for a dataset, begin by creating an Atlas object as above, and then create an Extra Data Request object that contains the dataset you want to enquire:

' Set up the request
Dim oRequest As New HpwSoap.ExtraDataRequest
oRequest.MAF = "uk-rm-paf-internal"

The above assumes the dataset you want to use is the UK Royal Mail PAF.

Now you can call the Extra Data method, passing in the Extra Data Request object and storing the return value in an Extra Data Response object:

' Do the lookup
Dim oResponse As HpwSoap.ExtraDataResponse = oAtlas.extraData(oRequest)

The Extra Data Response object contains an array of Extra Data fields you can request, along with a status code and description.

lstExtraData.Items.Clear()
If Not oResponse.ExtraData Is Nothing Then
  For Each s In oResponse.ExtraData
    lstExtraData.Items.Add(s)
  Next
End If

' Status
If oResponse.StatusCode > 0 Then
  MsgBox(oResponse.StatusDesc)
End If

The above assumes you want to display the fields in a list box.

If there is a problem, for example if the token username or token password is incorrect, an exception will be thrown. The exception message will contain information about the cause of the problem:

Try

  ... ' all of the code above

Catch ex As System.Exception
  MsgBox(ex.Message)
End Try

Request

Now that you have discovered what Extra Data is available you can request some or all of this data to be returned with your postcode lookups.

You can specify an array of Extra Data field names in the Extra Data property of the Postcode Lookup Request object.

If lstExtraData.CheckedItems.Count > 0 Then
  Dim extraData As New List(Of String)
  For Each o In lstExtraData.CheckedItems
    extraData.Add(o)
  Next
  oRequest.ExtraData = extraData.ToArray()
End If

The above assumes you want to request those fields that have been checked in a list box.

Retrieval

When processing your Postcode Lookup Response, you can check each Match Type for the existence of an Extra Data Record and then retrieve all the items contained within:

If Not oMatchType.ExtraDataRecord Is Nothing Then
  For Each oExtraDataRecordType In oMatchType.ExtraDataRecord
    For Each oExtraDataRecordItemType In oExtraDataRecordType.Item
      If Not oExtraDataRecordItemType.Value Is Nothing Then
        MsgBox(oExtraDataRecordItemType.Value)
      End If
    Next
  Next
End If

How do I get version information?

Getting version information is a good way to verify that you can connect to the service without costing you any of your clicks. The version information may also be helpful should you need to contact Hopewiser support with an enquiry about your service.

Begin by creating an Atlas object as above, and then create a Version Request object:

' Set up the request
Dim oRequest As New HpwSoap.VersionRequest

Now you can call the Version method, passing in the Version Request object and storing the return value in a Version Response object:

' Do the lookup
Dim oResponse As HpwSoap.VersionResponse = oAtlas.Version(oRequest)

The Version Response object contains the version of the Server and the version of Atlas, along with a status code and description.

' Server version
If Not oResponse.SoapAddrSvr Is Nothing Then
  MsgBox(oResponse.SoapAddrSvr)
End If

' Atlas version
If Not oResponse.Atlas Is Nothing Then
  MsgBox(oResponse.Atlas)
End If

' Status
If oResponse.StatusCode > 0 Then
  MsgBox(oResponse.StatusDesc)
End If

If there is a problem, for example if the token username or token password is incorrect, an exception will be thrown. The exception message will contain information about the cause of the problem:

Try

  ... ' all of the code above

Catch ex As System.Exception
  MsgBox(ex.Message)
End Try