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.

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

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 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

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