SOAP API Postcode Lookup Walkthrough

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

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

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

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.

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.

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