Phonematch web service VB.NET example

The following VB.NET code example enables you to easily get up and running with the Phonematch web service. Simply use the authentication credentials supplied to you on sign up which we have made available to you in the My Account section.

You will likely prefer to use one of of the available OAuth libraries to handle client authentication. The OAuth library used in the following example is listed separately.

Whilst our code examples demonstrate the breadth of our capabilities, all of our examples are created using demo data and do not contain real or live personal data relating to data subjects.

´╗┐Imports System.Collections.Generic
Imports System.Diagnostics
Imports System.IO
Imports System.Net
Imports System.Web.Script.Serialization
' note that my project name was called Phonematch_VB
Imports Phonematch_VB.OAuth
Namespace Tracesmart.VBNet.Api
    Public Class PhonematchService
        ' Your consumer key and secret as supplied by Tracesmart
        Private Const ConsumerKey As String = "b8e601941ad09b9478ac76c25b3bb46e10b8bdad"
        Private Const ConsumerSecret As String = "3065d6fa76t2da717bc5765388a8795a45245583"
        Public Sub MakeTestRequest()
            Dim parameters As IDictionary(Of String, String) = New Dictionary(Of String, String)() From { _
             {"landlineService", "A"}, _
             {"mobileService", "A"}, _
             {"forename", "Heather"}, _
             {"middleName", "Jane"}, _
             {"surname", "Russell"}, _
             {"address1", "201 Julius Road"}, _
             {"address2", "Bristol"}, _
             {"address3", ""}, _
             {"address4", ""}, _
             {"address5", ""}, _
             {"postcode", "BS7 8EU"}, _
             {"requestReference", "My Unique Reference"}, _
             {"ignoreNumbers", "07777111112"} _
            Dim response = New PhonematchService().MakeRequest(parameters)
            Dim matches = TryCast(response("matches"), Object())
            Debug.WriteLine("Found " & matches.Length & " possible matches")
            For Each match As IDictionary(Of String, Object) In matches
        End Sub
        Public Function MakeRequest(parameters As IDictionary(Of String, String)) As IDictionary(Of String, Object)
            Dim httpWebRequest = BuildRequest(parameters)
                Using httpWebResponse = DirectCast(httpWebRequest.GetResponse(), HttpWebResponse)
                    Dim jsonResponse = ReadResponseToText(httpWebResponse)
                    Debug.WriteLine("Received json from the server:")
                    Return New JavaScriptSerializer().Deserialize(Of IDictionary(Of String, Object))(jsonResponse)
                End Using
            Catch ex As WebException
                Throw New PhonematchServiceException(If(ReadResponseToText(ex.Response), ex.Message), ex)
            End Try
        End Function
        Private Function ReadResponseToText(response As WebResponse) As String
            If response Is Nothing Then
                Return Nothing
            End If
            Using responseStream = New StreamReader(response.GetResponseStream())
                Return responseStream.ReadToEnd()
            End Using
        End Function
        Private Function BuildRequest(parameters As IDictionary(Of String, String)) As HttpWebRequest
            ' This is a live API, please contact us if you need to perform load, volume or security testing
            Dim rawRequestUrl = New Uri("" & ToQueryString(parameters))
            Dim normalizedUrl As String
            Dim requestParameters As String
            Dim oAuth = New OAuthBase()
            Dim signature = oAuth.GenerateSignature(rawRequestUrl, ConsumerKey, ConsumerSecret, Nothing, Nothing, "POST", _
             oAuth.GenerateTimeStamp(), oAuth.GenerateNonce(), OAuthBase.SignatureTypes.HMACSHA1, normalizedUrl, requestParameters)
            Dim requestUrl = New Uri(normalizedUrl)
            Dim httpRequest = DirectCast(System.Net.WebRequest.Create(requestUrl), HttpWebRequest)
            httpRequest.Method = "POST"
            httpRequest.ContentType = "application/x-www-form-urlencoded"
            Using requestStream = New StreamWriter(httpRequest.GetRequestStream())
                requestStream.Write(requestParameters & "&oauth_signature=" & OAuthBase.UrlEncode(signature))
            End Using
            Return httpRequest
        End Function
        Private Function ToQueryString(parameters As IDictionary(Of String, String)) As String
            Return "?" & String.Join(
                "&", New List(Of String)(parameters.Keys).ConvertAll(
                    Function(key) String.Format(
                        "{0}={1}", OAuthBase.UrlEncode(key), OAuthBase.UrlEncode(parameters(key))
        End Function
    End Class
    Public Class PhonematchServiceException
        Inherits Exception
        Public Sub New(message As String, innerException As Exception)
            MyBase.New(message, innerException)
        End Sub
    End Class
End Namespace

An example of code that might make use of the previous class is listed below:

´╗┐Public Class _Default
    Inherits System.Web.UI.Page
    Protected Sub Page_Load(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Load
        Dim phonematch = New Tracesmart.VBNet.Api.PhonematchService()
    End Sub
End Class

From this juncture you should refer to the higher level documentation which explains how to send a request.