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 Address Sample Documentation (PDF). You can also download the .NET Address 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.

1. 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 username and password:

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

The above assumes you have stored your username and 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

2. 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 username or 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

 

3. How do I search for an address?

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 username or 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.

1. How do I customise what is returned?

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.

2. 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 Address Details Request object that is passed into the Address Details 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.

 

3. How do I search against a different dataset?

You can specify a dataset in the MAF property of the Address Search 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.

4. 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 username or 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

5. 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 username or 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