SOAP API Address Search 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

Initial Search

Begin by creating an Atlas object as above, and then create an Address Search Request object that contains your address:

' Set up the request
Dim oRequest As New HpwSoap.AddressSearchRequest
oRequest.Input1 = txtInput.Lines(0)
oRequest.Input2 = txtInput.Lines(1)
oRequest.Input3 = txtInput.Lines(2)
oRequest.Input4 = txtInput.Lines(3)
oRequest.Input5 = txtInput.Lines(4)
...

The above assumes the address you want to search for has been typed into a multi-line text box named txtInput.

To search for this address against your default dataset and using the default options, call the Address Search method, passing in the Address Search Request object and storing the return value in an Address Search Response object:

' Do the lookup
Dim oResponse As HpwSoap.AddressSearchResponse = oAtlas.AddressSearch(oRequest)

The Address Search Response object contains an array of Match Type objects, along with a status code and description.

For Each oMatchType In oResponse.Match
  MsgBox(oMatchType.SID & ", " & oMatchType.Text)
Next

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

You will most likely want to display the matches in a tree, list or 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

Drill down

If a match has further information available, its Expandable property will be Yes. For example, a matching street could be expanded to show the premises on that street, or a matching district could be expanded to show streets within that district.

To get these details for a match, begin by creating an Atlas object as above, and then create an Address Expand Request object that contains the SID of the match you want details for:

' Set up the request
Dim oRequest As New HpwSoap.AddressExpandRequest
oRequest.SID = oMatchType.SID

Now you can call the Address Expand method, passing in the Address Expand Request object and storing the result in an Address Expand Response object:

' Do the lookup
Dim oResponse As HpwSoap.AddressExpandResponse = oAtlas.AddressExpand(oRequest)

Like the Address Search Response, the Address Expand Response object also contains an array of Match Type objects, along with a status code and description.

For Each oMatchType In oResponse.Match
  MsgBox(oMatchType.SID & ", " & oMatchType.Text)
Next

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

Again, you will most likely want to display the matches in a tree, list or grid but here we are just displaying them in a message box for simplicity.

Final Selection

To get the address details for a Match Type, begin by creating an Atlas object as above, and then create an Address Details Request object that contains the SID of the match you want details for:

' Set up the request
Dim oRequest As New HpwSoap.AddressdetailsRequest
oRequest.SID = oMatchType.SID

Now you can call the Address Details method, passing in the Address Details Request object and storing the result in an Address Details Response object:

' Do the lookup
Dim oResponse As HpwSoap.AddressDetailsResponse = oAtlas.AddressDetails(oRequest)

The Address Details 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 Address Details 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.

You can create an Address Search Request Options object containing the search settings you want, and then add this to the Address Search Request object that is passed into the Address Search method.

Dim oRequestOptions As New HpwSoap.addressSearchRequestOptionsType

oRequestOptions.SearchMethod = 0 ' 0=Single Step, 1=Flatten
oRequestOptions.SearchMethodSpecified = True

oRequestOptions.MaxMatches = 400

... ' other options

oRequest.RequestOptions = oRequestOptions

You can also create an Address Details Request Options object containing the details settings you want, and then add this to the Address Details Request object that is passed into the Address Details method.

Dim oRequestOptions As New HpwSoap.addressDetailsRequestOptionsType

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

... ' other options

oRequest.RequestOptions = oRequestOptions

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

Some options, like Search Method and 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 Address Search Request object.

oRequest.MAF = "uk-rm-paf"

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"

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 address searches.

You can specify an array of Extra Data field names in the Extra Data property of the Address Details 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 Address Details 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