Page tree
Skip to end of metadata
Go to start of metadata


Introduction


DOTS Address Validation Canada 2 (AVCA2) is a publicly available XML web service that provides parsed and corrected information about a physical Canadian address. The service provides corrected information such as the correct street location and postal code as well as address fragments and locational metadata. AVCA2 can provide instant address verification and correction to websites or enhancement to contact lists. However, the output from AVCA2 must be considered carefully before the existence or non-existence of an address is decided.





If you are an existing client and are using the previous version of this service then please click on the following link.

DOTS Address Validation CA

Integration

Integrating AVCA2 into your application should be easy and straightforward. If you are using a common platform, Service Objects may already have sample code built that you can use:
https://www.serviceobjects.com/developers/sample-code/ 

However, if you are using a common platform that does not already have sample code, you can ask Service Objects to build you an example. Email support@serviceobjects.com for more details.


Web Service Structure:

Web services are methods that integrate with other applications via the web, and encapsulate tricky business logic. Web services are too large of a topic to cover in this document, but Service Objects has developed its web services to be as easy to integrate and as accessible as possible. AVCA is a public XML web service that supports SOAP, POST and GET operations.

The host path, or physical location of the web service is here: 
https://trial.serviceobjects.com/avca2/api.svc

A test page for the web service can be found here:
https://trial.serviceobjects.com/avca2/

The location of the WSDL, or Web Service Definition Language document, is here (This is also accessible via the "Service Definition" link.): 
https://trial.serviceobjects.com/avca2/api.svc?WSDL


Important Note!
SOAP is done via POST, only with special XML markup in the post-body.


This XML is the definition of the web service, meaning its inputs, outputs, operations, and the like. Most likely, you will have another tool read this WSDL and make the operations available to you in your application. Whenever your utilities or IDE asks for a WSDL path to AVCA, you can provide this one. 
Every web service has operations that it offers to subscribers – methods that do different work and return different output. Examining the link above, you will notice several of these operations available, which are described in detail later on. 


Code Snippets




Address Validation Canada 2 C# Code Snippet
response = ws.ValidateCanadianAddressV2(Address.Text, Address2.Text, Municipality.Text, Province.Text, PostalCode.Text, Language.Text, LicenseKey.Text);
if ((response == null || (response.Error != null && response.Error.TypeCode == "3")))
{
	throw new Exception();
	
}
else
{
	if (response.Error != null)
		ProcessErrorResponse(response.Error);
	else
		ProcessValidResponse(response.CanadianAddressInfoV2);
}


Address Validation Canada 2 Java Code Snippet
outputs = soap.validateCanadianAddressV2(address, address2, municipality, province, postalcode, language, licenseKey);
avca2error = outputs.getError();
if(avca2error !=null && avca2error.getTypeCode() == "3")
{
	throw new Exception();	
}
}
catch(Exception e)
{	//FAILOVER- USE BACKUP NOW
	try{
		//CALL SOAP USING BACKUP URL (Change the endpoint)
		outputs = soap.validateCanadianAddressV2(address, address2, municipality, province, postalcode, language, licenseKey);
		avca2error = outputs.getError();
	}
	catch(Exception ex)
	{
	
		throw new Exception("Both Primary and Backup soap calls failed: " + ex.getMessage());
	}
}


Address Validation Canada 2 PHP Code Snippets
$URL = "https://trial.serviceobjects.com/avca2/api.svc?wsdl";
//use backup url once given purchased license key
$backupURL = "https://trial.serviceobjects.com/avca2/api.svc?wsdl";
try{
	
			  
				$client = new SoapClient($URL);
	//$soapClient = new SoapClient($URL, array( "trace" => 1 ));
				$outputs = $client->ValidateCanadianAddressV2($params)->ValidateCanadianAddressV2Result;
				
				if (empty($outputs))
				{
					$backupClient = new SoapClient($backupURL);
					$outputs = $client->ValidateCanadianAddressV2($params)->ValidateCanadianAddressV2Result;
				}


Address Validation Canada 2 RoR Rest Code Snippets
class RequestsController < ApplicationController

	def show 
		@request = Request.find(params[:id])
		#Formats inputs into a hash to pass to Soap Client
		#Hash Keys must be named as they are shown here.
		message = 	{					
					"Address" => @request.address1,
					"Address2" => @request.address2,
					"City" => @request.municipality,
					"State" => @request.province,
					"PostalCode" => @request.postalcode,
					"Language" => @request.language,
					"LicenseKey" => @request.licensekey,
					}
		#Implemented to make the code more readable when accessing the hash			
		@avca2response = :validate_canadian_address_v2_response
		@avca2result = :validate_canadian_address_v2_result
		@avca2info = :canadian_address_info_v2
		@avca2error = :error

		#Set Primary and Backup URLs here as needed
		dotsAVCA2Primary = "https://trial.serviceobjects.com/avca2/api.svc?WSDL"
		dotsAVCA2Backup = "https://trial.serviceobjects.com/avca2/api.svc?WSDL"

		begin
			#initializes the soap client. The convert request keys global is necessary to receive a response from the service.
			client = Savon.client(	wsdl: dotsAVCA2Primary,
									element_form_default: :qualified,
									convert_request_keys_to: :camelcase
								 )
			#Calls the operation with given inptus and converts response to a hash.
			response = client.call(:validate_canadian_address_v2, message: message).to_hash

			#Checks to see what results came back from the service
			processresults(response)			
			
		#If an error occurs during the call, this will use the backup url and attempt to retrieve data.
		rescue Savon::Error => e
			begin
			backupclient = Savon.client(	wsdl: dotsAVCA2Backup,
											element_form_default: :qualified,
											convert_request_keys_to: :camelcase
									   )
			#Sets the response to the backclient call to the operation and converts response to a hash.
			response = backupclient.call(:validate_canadian_address_v2, message: message).to_hash
			processresults(response)
			end
		end
	end
	private 
	def processresults(response)	
			#Processes Error Response from soap Client		
			#Processes Valid response from soap client	
		
	end
end


Address Validation Canada 2 Python Code Snippet
    mAddress =  Address.get()
    if mAddress is None or  mAddress == "":
         mAddress = " "
    mAddress2 = Address2.get()
    if mAddress2 is None or mAddress2 == "":
        mAddress2 = " "
    mMunicipality = Municipality.get()
    if mMunicipality is None or mMunicipality == "":
        mMunicipality = " "
    mProvince = Province.get()
    if mProvince is None or mProvince == "":
        mProvince = " "
    mPostalCode = PostalCode.get()
    if mPostalCode is None or mPostalCode == "":
        mPostalCode = " "
    mLanguage = Language.get()
    if mLanguage is None or mLanguage == "":
        mLanguage = " "
    mLicenseKey = LicenseKey.get()
    if mLicenseKey is None or mLicenseKey == "":
        mLicenseKey = " "

    #Set the primary and backup URLs as needed
    primaryURL = 'https://trial.serviceobjects.com/avca2/api.svc?WSDL'
    backupURL = 'https://trial.serviceobjects.com/avca2/api.svc?WSDL'
     #This block of code calls the web service and prints the resulting values to the screen
    try:
        client = Client(primaryURL)
        result = client.service.ValidateCanadianAddressV2(Address=mAddress, Address2=mAddress2, Municipality=mMunicipality, Province=mProvince, PostalCode=mPostalCode, Language=mLanguage, LicenseKey=mLicenseKey)
        #Handel response and check for errors

    #Tries the backup URL if the primary URL failed
    except:
        try:
            client = Client(backupURL)
            result = client.service.ValidateCanadianAddressV2(Address=mAddress, Address2=mAddress2, Municipality=mMunicipality, Province=mProvince, PostalCode=mPostalCode, Language=mLanguage, LicenseKey=mLicenseKey)
           #Handel response and check for errors

        #If the backup call failed then this will display an error to the screen
        except:
            Label(swin.window, text='Error').pack()
			print (result)


Address Validation 2 Canada Code Snippet
<!--Makes Request to web service --->
<cfscript>
		try
		{
			if (isDefined("form.Action") AND Action neq "")
			{
				wsresponse = CreateObject("webservice", "https://trial.serviceobjects.com/avca2/api.svc?WSDL");							  
				outputs = wsresponse.validateCanadianAddressV2("#Address#", "#Address2#", "#Municipality#", "#Province#", "#PostalCode#", "#Language#", "#LicenseKey#");
			}
		}
	catch(any Exception){
		try
			{
				if (isDefined("form.Action") AND Action neq "")
				{
					wsresponse = CreateObject("webservice", "https://trial.serviceobjects.com/avca2/api.svc?WSDL");							  
					outputs = wsresponse.validateCanadianAddressV2("#Address#", "#Address2#", "#Municipality#", "#Province#", "#PostalCode#", "#Language#", "#LicenseKey#");
				}
			}
			catch(any Exception)	
				{
		  		 writeoutput("An Error Has Occured. Please Reload and try again: #Exception.message#");		  		 
		 		}
	    }
</cfscript>


Address Validation 2 Canada Code Snippet
Try
    Dim ws As New AVCA2.ValidateCanada2Client
    Dim response As AVCA2.CanadianAddressResponseV2
    response = ws.ValidateCanadianAddressV2(Address.Text, Address2.Text, Municipality.Text, Province.Text, PostalCode.Text, Language.Text, LicenseKey.Text)
    If (response Is Nothing) Then
        ProcessValidResponse(response)
    Else
        ProcessErrorResponse(response.Error)
    End If

Catch er As Exception
    ''Set the Primary and Backup Service References as necessary
    Try
        Dim wsbackup As New AVCA2.ValidateCanada2Client
        Dim response As AVCA2.CanadianAddressResponseV2
        response = wsbackup.ValidateCanadianAddressV2(Address.Text, Address2.Text, Municipality.Text, Province.Text, PostalCode.Text, Language.Text, LicenseKey.Text)
        If (response.Error Is Nothing) Then
            ProcessValidResponse(response)
        Else
            ProcessErrorResponse(response.Error)
        End If
    Catch ex As Exception
        resultsLabel.Visible = True
        resultsLabel.Text = ex.Message
    End Try
End Try


Address Validation Canada 2 Apex Code Snippet
wwwServiceobjectsCom.CanadianAddressResponseV2 result;
try{
wwwServiceobjectsCom.DOTSAVCA2 client = new wwwServiceobjectsCom.DOTSAVCA2();
result = client.ValidateCanadianAddressV2([Address], [Address2], [Municipality], [Province], [PostalCode], [Language], [LicenseKey]);
}
catch(Exception ex){
 //If the first request failed try the failover endpoint
wwwServiceobjectsCom.DOTSAVCA2 backupClient = new wwwServiceobjectsCom.DOTSAVCA2();
//The backup environment will be provided to you upon purchasing a production license key
backupClient.endpoint_x = 'https://trial.serviceobjects.com/AVCA2/api.svc/soap';
result = backupClient.ValidateCanadianAddressV2([Address], [Address2], [Municipality], [Province], [PostalCode], [Language], [LicenseKey]);
}




Address Validation Canada 2 TSQL Code Snippet
SET @requestBody ='<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">'+
				   '<s:Body>'+
				   '<ValidateCanadianAddressV2 xmlns="http://www.serviceobjects.com">'+
				   '<Address>' + @address + '</Address>'+
				   '<Address2>' + @address2 + '</Address2>'+
				   '<Municipality>' + @municipality + '</Municipality>'+
				   '<Province>' + @province + '</Province>'+
				   '<PostalCode>' + @postalcode + '</PostalCode>'+
				   '<Language>' + @language + '</Language>'+
				   '<LicenseKey>' + @key + '</LicenseKey>'+
				   '</ValidateCanadianAddressV2>'+
				   '</s:Body>'+
				   '</s:Envelope>'

SET @requestLength = LEN(@requestBody)

	--If a production key is purchased, this will execute the failover 
IF @isLiveKey = 1
BEGIN
	EXEC sp_OACreate 'MSXML2.ServerXMLHttp', @obj OUT
	EXEC sp_OAMethod @obj, 'Open', NULL, 'POST', 'https://trial.serviceobjects.com/AVCA2/api.svc/soap', false
	EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'HOST', 'ws.serviceobjects.com'
	EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'Content-Type', 'text/xml; charset=UTF-8'
	EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'SOAPAction', '"http://www.serviceobjects.com/IValidateCanada2/ValidateCanadianAddressV2"'
	EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'Content-Length', @requestLength 
	EXEC sp_OAMethod @obj, 'send', NULL, @requestBody
	EXEC sp_OAGetProperty @obj, 'Status', @responseCode OUTPUT
	EXEC sp_OAGetProperty @obj, 'StatusText', @statusText OUTPUT
	EXEC sp_OAGetProperty @obj, 'responseText', @response OUTPUT
			
	--Checks the Response for a fatal error or if null. 
	IF @response IS NULL
	BEGIN
		EXEC sp_OACreate 'MSXML2.ServerXMLHttp', @obj OUT
		EXEC sp_OAMethod @obj, 'Open', NULL, 'POST', 'https://trial.serviceobjects.com/AVCA2/api.svc/soap', false
		EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'HOST', 'wsbackup.serviceobjects.com'
		EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'Content-Type', 'text/xml; charset=UTF-8'
		EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'SOAPAction', '"http://www.serviceobjects.com/IValidateCanada2/ValidateCanadianAddressV2"'
		EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'Content-Length', @requestLength 
		EXEC sp_OAMethod @obj, 'send', NULL, @requestBody
		EXEC sp_OAGetProperty @obj, 'Status', @responseCode OUTPUT
		EXEC sp_OAGetProperty @obj, 'StatusText', @statusText OUTPUT
		EXEC sp_OAGetProperty @obj, 'responseText', @response OUTPUT
	END
END


Address Validation Canada 2 TSQL Code Snippet
SET @requestBody ='<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">'+
				   '<s:Body>'+
				   '<ValidateCanadianAddressV2 xmlns="http://www.serviceobjects.com">'+
				   '<Address>' + @address + '</Address>'+
				   '<Address2>' + @address2 + '</Address2>'+
				   '<Municipality>' + @municipality + '</Municipality>'+
				   '<Province>' + @province + '</Province>'+
				   '<PostalCode>' + @postalcode + '</PostalCode>'+
				   '<Language>' + @language + '</Language>'+
				   '<LicenseKey>' + @key + '</LicenseKey>'+
				   '</ValidateCanadianAddressV2>'+
				   '</s:Body>'+
				   '</s:Envelope>'

SET @requestLength = LEN(@requestBody)

	--If a production key is purchased, this will execute the failover 
IF @isLiveKey = 1
BEGIN
	EXEC sp_OACreate 'MSXML2.ServerXMLHttp', @obj OUT
	EXEC sp_OAMethod @obj, 'Open', NULL, 'POST', 'https://trial.serviceobjects.com/AVCA2/api.svc/soap', false
	EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'HOST', 'ws.serviceobjects.com'
	EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'Content-Type', 'text/xml; charset=UTF-8'
	EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'SOAPAction', '"http://www.serviceobjects.com/IValidateCanada2/ValidateCanadianAddressV2"'
	EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'Content-Length', @requestLength 
	EXEC sp_OAMethod @obj, 'send', NULL, @requestBody
	EXEC sp_OAGetProperty @obj, 'Status', @responseCode OUTPUT
	EXEC sp_OAGetProperty @obj, 'StatusText', @statusText OUTPUT
	EXEC sp_OAGetProperty @obj, 'responseText', @response OUTPUT
			
	--Checks the Response for a fatal error or if null. 
	IF @response IS NULL
	BEGIN
		EXEC sp_OACreate 'MSXML2.ServerXMLHttp', @obj OUT
		EXEC sp_OAMethod @obj, 'Open', NULL, 'POST', 'https://trial.serviceobjects.com/AVCA2/api.svc/soap', false
		EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'HOST', 'wsbackup.serviceobjects.com'
		EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'Content-Type', 'text/xml; charset=UTF-8'
		EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'SOAPAction', '"http://www.serviceobjects.com/IValidateCanada2/ValidateCanadianAddressV2"'
		EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'Content-Length', @requestLength 
		EXEC sp_OAMethod @obj, 'send', NULL, @requestBody
		EXEC sp_OAGetProperty @obj, 'Status', @responseCode OUTPUT
		EXEC sp_OAGetProperty @obj, 'StatusText', @statusText OUTPUT
		EXEC sp_OAGetProperty @obj, 'responseText', @response OUTPUT
	END
END



Address Validation Canada 2 C# Rest Code Snippet
string primaryurl = "https://trial.serviceobjects.com/avca2/api.svc/ValidateCanadianAddressV2?Address=" + address + "&Address2=" + address2 + "&Municipality=" + municiaplity + "&Province=" + province + "&PostalCode=" + postalcode + "&Language=" + language + "&LicenseKey=" + licensekey;
string backupurl = "https://trial.serviceobjects.com/avca2/api.svc/ValidateCanadianAddressV2?Address=" + address + "&Address2=" + address2 + "&Municipality=" + municiaplity + "&Province=" + province + "&PostalCode=" + postalcode + "&Language=" + language + "&LicenseKey=" + licensekey;

CanadianAddressResponseV2 wsresponse = httpGet(primaryurl);


//checks if a response was returned from the service, uses the backup url if response is null or a fatal error occured.
if (wsresponse == null || (wsresponse.Error != null && wsresponse.Error.TypeCode == "3")) ;
{
	wsresponse = httpGet(backupurl);
}

if (wsresponse.Error != null)
{
	ProcessErrorResponse(wsresponse.Error);
}
else
{
	ProcessSuccessfulResponse(wsresponse.CanadianAddressInfoV2);
}


Address Validation Canada 2 Java Rest Code Snippet
String mainurl = "https://trial.serviceobjects.com/avca2/api.svc/ValidateCanadianAddressV2?Address="+ address + "&Address2=" + address2 + "&Municipality=" + municipality + "&Province=" + province + "&PostalCode=" + postalcode + "&Language=" + language + "&LicenseKey=" + licensekey;
String backupurl = "https://trial.serviceobjects.com/avca2/api.svc/ValidateCanadianAddressV2?Address="+ address + "&Address2=" + address2 + "&Municipality=" + municipality + "&Province=" + province + "&PostalCode=" + postalcode + "&Language=" + language + "&LicenseKey=" + licensekey;

//System.out.println(mainurl);
	
AVCA2RestClient avca2rest = new AVCA2RestClient();	
JSONObject results = new JSONObject();
results = avca2rest.AddressResponse(mainurl, backupurl);



Address Validation Canada 2 PHP Rest Code Snippets
$URL = "https://trial.serviceobjects.com/avca2/api.svc/ValidateCanadianAddressV2?Address=".urlencode($Address)."&Address2=".urlencode($Address2)."&Municipality=".urlencode($Municipality)."&Province=".urldecode($Province)."&PostalCode=".urldecode($PostalCode)."&Language=".urldecode($Language)."&LicenseKey=".urlencode($LicenseKey);
//use backup url once given purchased license key
$backupURL = "https://trial.serviceobjects.com/avca2/api.svc/ValidateCanadianAddressV2?Address=".urlencode($Address)."&Address2=".urlencode($Address2)."&Municipality=".urlencode($Municipality)."&Province=".urldecode($Province)."&PostalCode=".urldecode($PostalCode)."&Language=".urldecode($Language)."&LicenseKey=".urlencode($LicenseKey);
try{
	// Get cURL resource
	$curl = curl_init();
	curl_setopt_array($curl, array(CURLOPT_RETURNTRANSFER => 1, CURLOPT_URL => $URL, CURLOPT_USERAGENT => 'Service Objects Address Validation Canada'));
	curl_setopt($curl, CURLOPT_TIMEOUT, 50); //timeout in seconds
	// Send the request & save response to $resp
	$resp = curl_exec($curl);
	
	// Close request to clear up some resources
	if($resp == false)
	{
		echo "IN back up block";
		curl_setopt_array($curl, array(CURLOPT_RETURNTRANSFER => 1, CURLOPT_URL => $backupURL, CURLOPT_USERAGENT => 'Service Objects Address Validation Canada'));
		curl_setopt($curl, CURLOPT_TIMEOUT, 50); //timeout in seconds
		// Send the request & save response to $resp
		$resp = curl_exec($curl);
		if($resp == false)
		{
			echo "<b> Both rest calls failed </b>";
			curl_close($curl);
			return;
		}
	
	
	}


Address Validation Canada 2 RoR Code Snippets
class RequestsController < ApplicationController
	
	def show
      @request = Request.find(params[:id])

      #This sets the default timeout for HTTParty get operation. This must be set in order to use the gem
      default_timeout = 10
      
      address = @request.address1
      address2 = @request.address2
      municipality = @request.municipality
      province = @request.province
      postalcode = @request.postalcode
      language = @request.language
      licensekey = @request.licensekey
            
      #Set Primary and Backup URLs as needed. This method encodes and standardizes the URI to pass to the REST service.
      primaryURL = URI.encode("https://trial.serviceobjects.com/AVCA2/api.svc/ValidateCanadianAddressV2?PostalCode=" + postalcode + "&Province=" + province + "&Municipality=" + municipality + "&Address2=" + address2 + "&Address=" + address + "&Language="+ language + "&LicenseKey=" + licensekey)
      backupURL = URI.encode("https://trial.serviceobjects.com/AVCA2/api.svc/ValidateCanadianAddressV2?PostalCode=" + postalcode + "&Province=" + province + "&Municipality=" + municipality + "&Address2=" + address2 + "&Address=" + address + "&Language="+ language + "&LicenseKey=" + licensekey)
      
      #These are set to access the hash that is returned
      @avca2result ="CanadianAddressResponseV2"
      @avca2info = "CanadianAddressInfoV2"
      @avca2error = "Error"
     	
        #Begins the call the RESTful web service
      begin
        response = HTTParty.get(primaryURL, timeout: default_timeout)
        #processes the response to display to the screen
        
        #Passes the response returned from HTTParty and processes them depending on the results
        processresults(response)
        
       rescue StandardError => e
       		begin
       		#uses the backupURl in the event that the service encountered an error
       		response = HTTParty.get(backupURL, timeout: default_timeout)
          
          #processes the response returned from using the backupURL
       		processresults(response)
      end
  end
	private 
      #processes HTTParty response and uses hash names to display
      #relevant info returned from the ServiceObjects web serivce
	def processresults(response)	
			#Processes Error Response from the web service		
			#Processes a valid response from the web service
	end
end


Address Validation Canada 2 Python Code Snippet
    mAddress =  Address.get()
    if mAddress is None or  mAddress == "":
         mAddress = " "
    mAddress2 = Address2.get()
    if mAddress2 is None or mAddress2 == "":
        mAddress2 = " "
    mMunicipality = Municipality.get()
    if mMunicipality is None or mMunicipality == "":
        mMunicipality = " "
    mProvince = Province.get()
    if mProvince is None or mProvince == "":
        mProvince = " "
    mPostalCode = PostalCode.get()
    if mPostalCode is None or mPostalCode == "":
        mPostalCode = " "
    mLanguage = Language.get()
    if mLanguage is None or mLanguage == "":
        mLanguage = " "
    mLicenseKey = LicenseKey.get()
    if mLicenseKey is None or mLicenseKey == "":
        mLicenseKey = " "

    #Set the Primary and backup URLs as necessary
    primaryURL = 'https://trial.serviceobjects.com/gcc/GeoCoderCanada.asmx/GetGeoLocation?'
    backupURL = 'https://trial.serviceobjects.com/gcc/GeoCoderCanada.asmx/GetGeoLocation?'
    #The Requests package allows the user to format the path parameters like so instead of having to manually insert them into the URL
    inputs = {"PostalCode": mPostalCode, 'Province': mProvince, 'Municipality': mMunicipality, 'Address2':mAddress2, 'Address': mAddress, 'Language': mLanguage, 'LicenseKey': mLicenseKey}
    try:
        result = requests.get(primaryURL, params=inputs)
        #Parses the XML response from the service into a python dictionary type
        outputs = xmltodict.parse(result.content)
        #Handel response and check for errors
    #Attempts to make a call to the service if the primary url failed
    except:
        try:
            result = requests.get(backupURL, params=inputs)
            #Parses the XML response from the service into a python dictionary type
            outputs = xmltodict.parse(result.content)
            #Handel response and check for errors
        #Prints an error if the primary and backup URLs failed
        except:
            Label(swin.window, text='Error').pack()
            print (result)


Address Validation Canada 2 ColdFusion Snippet
<!--Makes Request to web service --->
<cfIf isDefined("form.Action") AND Action neq "" >
	<cftry>
		<cfset primaryURL = "https://trial.serviceobjects.com/AVCA2/api.svc/ValidateCanadianAddressV2?PostalCode=#PostalCode#&Province=#Province#&Municipality=#Municipality#&Address2=#Address2#&Address=#Address#&Language=#Language#&LicenseKey=#LicenseKey#">
		<cfhttp url="#primaryURL#" method="get" result="response">
		<cfset outputs = XmlParse(response.FileContent)>
		<cfcatch>
			<cftry>
				<cfset backupURL = "https://trial.serviceobjects.com/AVCA2/api.svc/ValidateCanadianAddressV2?PostalCode=#PostalCode#&Province=#Province#&Municipality=#Municipality#&Address2=#Address2#&Address=#Address#&Language=#Language#&LicenseKey=#LicenseKey#">
				<cfhttp url="#backupURL#" method="get" result="response">
				<cfset outputs = XmlParse(response.FileContent)>				
				<cfcatch >
					<cfoutput >
						The Following Error Occured: #response.StatusCode#
					</cfoutput>
				</cfcatch>
			</cftry>
		</cfcatch>
	</cftry>
</cfif>

		


Address Validation 2 Canada Code Snippet
'encodes the URLs for the get Call. Set the primary and back urls as necessary
Dim primaryurl As String = "https://trial.serviceobjects.com/AVCA2/api.svc/ValidateCanadianAddressV2?PostalCode=" + postalcode + "&Province=" + province + "&Municipality=" + municipality + "&Address2=" + address2 + "&Address=" + address + "&Language=" + language + "&LicenseKey=" + licensekey
Dim backupurl As String = "https://trial.serviceobjects.com/AVCA2/api.svc/ValidateCanadianAddressV2?PostalCode=" + postalcode + "&Province=" + province + "&Municipality=" + municipality + "&Address2=" + address2 + "&Address=" + address + "&Language=" + language + "&LicenseKey=" + licensekey
Dim wsresponse As AVCA2Response.CanadianAddressResponseV2 = httpGet(primaryurl)

'checks if a response was returned from the service, uses the backup url if response is null or a fatal error occured.
If wsresponse Is Nothing OrElse (wsresponse.[Error] IsNot Nothing AndAlso wsresponse.[Error].TypeCode = "3") Then
    wsresponse = httpGet(backupurl)
End If
If wsresponse.[Error] IsNot Nothing Then
    ProcessErrorResponse(wsresponse.[Error])
Else
    ProcessSuccessfulResponse(wsresponse)

End If


Address Validation Canada 2 TSQL Rest Code Snippet
BEGIN
	SET @sUrl = 'https://trial.serviceobjects.com/avca2/api.svc/ValidateCanadianAddressV2?Address=' + @address + '&Address2=' + @address2 + '&Municipality=' + @municipality + '&Province=' + @province + '&PostalCode=' + @postalcode + '&Language=' + @language + '&LicenseKey=' + @key
	EXEC sp_OACreate 'MSXML2.ServerXMLHttp', @obj OUT
	EXEC sp_OAMethod @obj, 'Open', NULL, 'Get', @sUrl, false
	EXEC sp_OAMethod @obj, 'send'
	EXEC sp_OAGetProperty @obj, 'responseText', @response OUT
			
	--Checks the Response for a fatal error or if null. 
	IF @response IS NULL
	BEGIN
		SET @sBackupUrl = 'https://trial.serviceobjects.com/avca2/api.svc/ValidateCanadianAddressV2?Address=' + @address + '&Address2=' + @address2 + '&Municipality=' + @municipality + '&Province=' + @province + '&PostalCode=' + @postalcode + '&Language=' + @language + '&LicenseKey=' + @key
		EXEC sp_OACreate 'MSXML2.ServerXMLHttp', @obj OUT
		EXEC sp_OAMethod @obj, 'Open', NULL, 'Get', @sBackupUrl, false
		EXEC sp_OAMethod @obj, 'send'
		EXEC sp_OAGetProperty @obj, 'responseText', @response OUT
	END
END


Address Validation Canada 2 REST Code Snippet
var primaryUrl = 'https://trial.serviceobjects.com/avca2/api.svc/ValidateCanadianAddressV2?Address=' + Address +'&Address2='+ Address2 + '&Municipality=' + Municipality +'&Province=' + Province +'&PostalCode=' + PostalCode + '&Language=' + Language +'&LicenseKey=' + LicenseKey;
var backupUrl = 'https://trial.serviceobjects.com/avca2/api.svc/ValidateCanadianAddressV2?Address=' + Address +'&Address2='+ Address2 + '&Municipality=' + Municipality +'&Province=' + Province +'&PostalCode=' + PostalCode + '&Language=' + Language +'&LicenseKey=' + LicenseKey;


var req = http.get(primaryUrl, function(res) {
	res.setEncoding('utf8');
	res.on('data', function (results) {

		//Sets up the XML to JSON parser.  JSON makes the response easier to handle.
		var parser = require('xml2js').Parser({explicitArray: false,ignoreAttrs: true});
		parser.parseString(results, function (err, outputs) {
			if (outputs.CanadianAddressResponseV2.Error !=  null)
			{
				//Indicates a Fatal error has occured. If this happens, the logic will then failover to the backup url
				if (outputs.CanadianAddressResponseV2.Error.TypeCode == "3")
				{
					var backupReq = http.get(backupUrl, function(backupRes) {
						backupRes.setEncoding('utf8');
						backupRes.on('data', function (results) {

								var parser = require('xml2js').Parser({explicitArray: false,ignoreAttrs: true});
								parser.parseString(results, function (err, outputs) {

									console.log("Backup Call Was Used.");
									response.end(JSON.stringify(outputs , null, 3));
								});
							});
						});
				}
				else
				{
					//Will Display the JSON Formatted Error Response here
					response.end(JSON.stringify(outputs, null, 3));
					return;
				}
			}
			else
			{
				//Will Display the JSON Formatted Valid Response here
				response.end(JSON.stringify(outputs, null, 3));
				return;
			}
		});
	});
});

You can find and download full sample code to our services in various languages (PHP, JAVA and C#) by clicking here. Below is a C# version.

If you are looking for a particular integration not listed in our documentation please contact us at support@serviceobjects.com.

C#
using System;
using System.Configuration;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
using DOTSAVCA2.com.serviceobjects.trial;
using System.Data;
 
namespace DOTSAVCA2
{
    public partial class avca2_soap : System.Web.UI.Page
    {
       static int WEB_SERVICE_REQUEST_TIMEOUT; //In milliseconds
       
        protected void Page_Load(object sender, EventArgs e)
        {
            ErrorLabel.Visible = false;
            ResultGrid.Visible = false;
            ErrorGrid.Visible = false;
            try
            {
                WEB_SERVICE_REQUEST_TIMEOUT = Convert.ToInt32(ConfigurationManager.AppSettings["WebServiceRequestTimeout"]);
            }
            catch (Exception ex)
            {
                ErrorLabel.Visible = true;
                ErrorLabel.Text = "Page load Error: " + ex.Message;
            }
           
        }
        //Handle the click image button event
        protected void btn_Validate_Click(object sender, EventArgs e)
        {
            try
            {
                CanadianAddressResponse response = ValidateAddress(inputAddress.Text, inputAddress2.Text, inputMunicipality.Text, inputProvince.Text, inputPostalCode.Text, inputLicenseKey.Text);
                ProcessResponse(response);
            }
            catch (Exception ex)
            {
                ErrorLabel.Visible = true;
                ErrorLabel.Text = ex.Message;
            }
        }
        //Create soap clients and request response from service
        private static CanadianAddressResponse ValidateAddress(string address, string address2, string municipality, string province, string postalCode, string LICENSE_KEY)
        {
            ValidateCanada2Client AVCA2Client_Primary = null;
            ValidateCanada2Client AVCA2Client_Backup = null;
            CanadianAddressResponse response = null;
            try
            {
                AVCA2Client_Primary = new ValidateCanada2Client("DOTSAVCA2PRIMARY");
                AVCA2Client_Primary.InnerChannel.OperationTimeout = new TimeSpan(0, 0, 0, WEB_SERVICE_REQUEST_TIMEOUT);
                response =  AVCA2Client_Primary.ValidateCanadianAddress(address, address2, municipality, province, postalCode, LICENSE_KEY);
                //NULL ERROR || FATAL ERROR RETURNED -- TRY BACKUP 
                if (response == null || (response.Error != null && response.Error.TypeCode == "3"))
                {
                    throw new Exception();
                }
                return response;
            }
            catch (Exception)
            {
                try
                {
                    AVCA2Client_Backup = new ValidateCanada2Client("DOTSAVCA2BACKUP");
                    AVCA2Client_Backup.InnerChannel.OperationTimeout = new TimeSpan(0, 0, 0, WEB_SERVICE_REQUEST_TIMEOUT);
                    return AVCA2Client_Backup.ValidateCanadianAddress(address, address2, municipality, province, postalCode, LICENSE_KEY);
                }
                catch (Exception e)
                {
                    throw e;
                }
                finally
                {
                    if (AVCA2Client_Backup != null) { AVCA2Client_Backup.Close(); }
                }
            }
            finally
            {
                if (AVCA2Client_Primary != null) { AVCA2Client_Primary.Close(); }
            }
            
        }
        //Process the returned object
        private void ProcessResponse(CanadianAddressResponse response)
        {
            try
            {
                if (response.Error == null)
                {
                    ProcessAddressValidateInfo(response.CanadianAddressInfo);
                }
                else
                {
                    ProccessErrorResult(response.Error);
                }
            }
            catch (Exception e)
            {
                throw e;
            }
        }
        //Process and display the error values
        private void ProccessErrorResult(Error error)
        {
            try
            {
                DataTable dtError = new DataTable();
                //A case statement is used here because it is often useful to do different
                //things depeneding on which general type of error occurs.
                //Handle the errors according to your production needs.
                switch (System.Convert.ToInt32(error.TypeCode))
                {
                    case 1:
                        //Authorization Error
                       
                        break;
                    case 2:
                        //User Input Error
                       
                        break;
                    case 4:
                        //Domain Specific Error
                      
                        break;
                    default:
                        //default (error code 3) Service Objects Fatal Error Error
                       
                        break;
                }
              
                dtError.Columns.Add(new DataColumn("Output", typeof(string)));
                dtError.Columns.Add(new DataColumn("Values", typeof(string)));
                dtError.Rows.Add("Type", error.Type);
                dtError.Rows.Add("TypeCode", error.TypeCode);
                dtError.Rows.Add("Desc", error.Desc);
                dtError.Rows.Add("DescCode", error.DescCode);
               
                ResultGrid.Visible = false;
                ErrorGrid.Visible = true;
                ErrorGrid.DataSource = new DataView(dtError);
                ErrorGrid.DataBind();
            }
            catch (System.Exception e)
            {
                throw e;
            }
        }
        //Process the returned object
        private void ProcessAddressValidateInfo(CanadianAddressInfo result)
        {
            
          
            /*declaring a table to hold the provider information*/
            try
            {
                DataTable dtProvider = new DataTable();
                //Proccess result
                //We just output it here but this would be a good place to save data
                //to a database or send an email etc.
                dtProvider.Columns.Add(new DataColumn("Output", typeof(string)));
                dtProvider.Columns.Add(new DataColumn("Values", typeof(string)));
               
                dtProvider.Rows.Add("Address", result.Address);
                dtProvider.Rows.Add("Address2", result.Address2);
                dtProvider.Rows.Add("Municipality", result.Municipality);
                dtProvider.Rows.Add("Province", result.Province);
                dtProvider.Rows.Add("PostalCode", result.PostalCode);
                dtProvider.Rows.Add("TimeZone", result.TimeZone);
                dtProvider.Rows.Add("AddressNumbeFragment", result.AddressNumberFragment);
                dtProvider.Rows.Add("StreetNameFragment", result.StreetNameFragment);
                dtProvider.Rows.Add("StreetTypeFragment", result.StreetTypeFragment);
                dtProvider.Rows.Add("DirectionalCodeFragment", result.DirectionalCodeFragment);
                dtProvider.Rows.Add("UnitTypeFragment", result.UnitTypeFragment);
                dtProvider.Rows.Add("UnitNumberFragment", result.UnitNumberFragment);
                dtProvider.Rows.Add("IsBOPox", result.IsPOBox);
                dtProvider.Rows.Add("BoxNumberFragment", result.BoxNumberFragment);
                dtProvider.Rows.Add("StationInfo", result.StationInfo);
                dtProvider.Rows.Add("DeliveryMode", result.DeliveryMode);
                dtProvider.Rows.Add("DeliveryInstallation", result.DeliveryInstallation);
                ResultGrid.Visible = true;
                ErrorGrid.Visible = false;
                ResultGrid.DataSource = new DataView(dtProvider);
                ResultGrid.DataBind();
            }
            catch (System.Exception e)
            {
                throw e;
            }
        }
    }
}


ValidateCanadianAddressExample Request and Response


URL Request: 
https://trial.serviceobjects.com/AVCA2/api.svc/CanadianAddress/K1K3B8/Ontario/Ottawa/%20/1200%20St%20Laurent%20Blvd/licenseKey?format=json


Json Response
{"CanadianAddressInfo":{"Address":"1200 ST. LAURENT BLVD","Address2":"","Municipality":"OTTAWA","Province":"ON","PostalCode":"K1K 3B8","TimeZone":"EASTERN","AddressNumberFragment":"1200","StreetNameFragment":"ST. LAURENT","StreetTypeFragment":"BLVD","DirectionalCodeFragment":"","UnitTypeFragment":"","UnitNumberFragment":"","IsPOBox":"False","BoxNumberFragment":"","StationInfo":"","DeliveryMode":"","DeliveryInstallation":""}}


URL Request: 
https://trial.serviceobjects.com/AVCA2/api.svc/CanadianAddress/K1K3B8/Ontario/Ottawa/%20/1200%20St%20Laurent%20Blvd/licenseKey?format=xml


XML Response
<CanadianAddressResponse xmlns="http://www.serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<CanadianAddressInfo>
<Address>1200 ST. LAURENT BLVD</Address>
<Address2/>
<Municipality>OTTAWA</Municipality>
<Province>ON</Province>
<PostalCode>K1K 3B8</PostalCode>
<TimeZone>EASTERN</TimeZone>
<AddressNumberFragment>1200</AddressNumberFragment>
<StreetNameFragment>ST. LAURENT</StreetNameFragment>
<StreetTypeFragment>BLVD</StreetTypeFragment>
<DirectionalCodeFragment/>
<UnitTypeFragment/>
<UnitNumberFragment/>
<IsPOBox>False</IsPOBox>
<BoxNumberFragment/>
<StationInfo/>
<DeliveryMode/>
<DeliveryInstallation/>
</CanadianAddressInfo>
</CanadianAddressResponse>

ValidateCanadianMunicipalityProvince Example Request and Response


URL Request:
https://trial.serviceobjects.com/AVCA2/api.svc/CanadianMunicipalityProvince/K1K3B8/Ontario/Ottowa/licenseKey?format=json


Json Response
{"CanadianAddressInfo":{"Address":"","Address2":"","Municipality":"OTTAWA","Province":"ON","PostalCode":"K1K 3B8","TimeZone":"EASTERN","AddressNumberFragment":"","StreetNameFragment":"","StreetTypeFragment":"","DirectionalCodeFragment":"","UnitTypeFragment":"","UnitNumberFragment":"","IsPOBox":"False","BoxNumberFragment":"","StationInfo":"","DeliveryMode":"","DeliveryInstallation":""}}


URL Request:
https://trial.serviceobjects.com/AVCA2/api.svc/CanadianMuncipalityProvince/K1K3B8/Ontario/Ottowa/licenseKey?format=xml


XML Response
<CanadianAddressResponse xmlns="http://www.serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<CanadianAddressInfo>
<Address/>
<Address2/>
<Municipality>OTTAWA</Municipality>
<Province>ON</Province>
<PostalCode>K1K 3B8</PostalCode>
<TimeZone>EASTERN</TimeZone>
<AddressNumberFragment/>
<StreetNameFragment/>
<StreetTypeFragment/>
<DirectionalCodeFragment/>
<UnitTypeFragment/>
<UnitNumberFragment/>
<IsPOBox>False</IsPOBox>
<BoxNumberFragment/>
<StationInfo/>
<DeliveryMode/>
<DeliveryInstallation/>
</CanadianAddressInfo>
</CanadianAddressResponse>

ParseCanadianAddress Example Request and Response


URL Request: 
https://trial.serviceobjects.com/AVCA2/api.svc/CanadianAddressFragments/K1K3B8/Ontario/Ottawa/%20/1200%20St%20Laurent%20Blvd/licenseKey?format=json


Json Response
{"CanadianAddressInfo":{"Address":"1200 ST LAURENT BLVD","Address2":"","Municipality":"OTTAWA","Province":"ON","PostalCode":"K1K 3B8","TimeZone":"","AddressNumberFragment":"1200","StreetNameFragment":"ST LAURENT","StreetTypeFragment":"BLVD","DirectionalCodeFragment":"","UnitTypeFragment":"","UnitNumberFragment":"","IsPOBox":"False","BoxNumberFragment":"","StationInfo":"","DeliveryMode":"","DeliveryInstallation":""}}


URL Request: 
https://trial.serviceobjects.com/AVCA2/api.svc/CanadianAddressFragments/K1K3B8/Ontario/Ottawa/%20/1200%20St%20Laurent%20Blvd/licenseKey?format=xml


XML Response
<CanadianAddressResponse xmlns="http://www.serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<CanadianAddressInfo>
<Address>1200 ST LAURENT BLVD</Address>
<Address2/>
<Municipality>OTTAWA</Municipality>
<Province>ON</Province>
<PostalCode>K1K 3B8</PostalCode>
<TimeZone/>
<AddressNumberFragment>1200</AddressNumberFragment>
<StreetNameFragment>ST LAURENT</StreetNameFragment>
<StreetTypeFragment>BLVD</StreetTypeFragment>
<DirectionalCodeFragment/>
<UnitTypeFragment/>
<UnitNumberFragment/>
<IsPOBox>False</IsPOBox>
<BoxNumberFragment/>
<StationInfo/>
<DeliveryMode/>
<DeliveryInstallation/>
</CanadianAddressInfo>
</CanadianAddressResponse>

List of Operations

ValidateCanadianAddressV(Recommended Operation) -validates an address's authenticity, and returns corrected address information for a given Canadian postal address.  Recommended )
ValidateCanadianAddress - validates an address's authenticity, and returns corrected address information for a given Canadian postal address.
ValidateCanadianMunicipalityProvince  - validates a Canadian municipality and province, and returns additional information about time zone and location.
ParseCanadianAddress - This operation provides address fragments based off of validated address inputs.

Operation Definitions

This document defines the input, output and behavior of the web service operations in DOTS Address Validation – Canada 2. 

ValidateCanadianAddressV2 (Recommended Operation)

This operation performs basic checks on user supplied inputs; Address1, Address2, Municipality, Province or Postal Code and returns verified Address, Municipality, Province and Postal Code in Canadian address recommended format which is upper cased. There is also a method to return proper cased addresses by appending "-Proper" to the language parameter (e.g Language=EN-Proper). This operation also returns time zone and a check on if the supplied location is a P.O. Box, General Delivery or Rural Route. This operation requires either a Postal Code or both Municipality and Province.  Providing all inputs is recommended, because it helps the validation proceed if some of the elements are malformed. 

Inputs 

ValidateCanadianAddressV2 Inputs 

Name

Type

Description

Address

String

Address line of the address to validate.
For example, "123 Main Street".

Address 2String

The Address2 of the address to validate. This will only be used in particular situations where the Address1 does not help in validating the address.

Municipality

String

The Municipality of the address to validate.

Province

String

The Province of the address to validate.

PostalCode

String

The Postal Code of the address to validate. A Postal Code isn't required, but if one is not provided, the Municipality and Province are required.

LanguageString

The Language to return the addresses as. Acceptable values are (English, EN, French, FR, EN-Proper, FR-Proper). Leaving this field blank will use the default behavior of returning addresses as English standardized if they are provided in English, and French standardized if provided in French. Adding the additional value "Proper" will apply proper casing to the output address.

LicenseKey

String

Your license key to use the service.
Sign up for a free trial key at
https://www.serviceobjects.com/products/address-geocoding/canada-address-validation

 
Outputs

CanadianAddressResponseV2 

All of the response objects are contained within the CanadianAddressResponseV2 object. 

NameTypeValuesDescription
CanadianAddressInfoV2ObjectVariesThe returned values of a valid Canadian Address.
ErrorObjectVariesThe returned error result from a failed address verification or user input error.
DebugString[]VariesUsed internally for testing.

 

 CanadianAddressInfoV2 

Name

Type

Values

Description

Address

String

Varies

The corrected Address line 1.

Address 2StringVariesThe corrected Address line 2

Municipality

String

Varies

The corrected Municipality.

Province

String

Varies

The corrected Province.

PostalCode

String

Varies

The corrected PostalCode.

TimeZone

String

Varies

The corresponding time zone from the validated address.

AddressNumberFragment

String

Varies

The parsed address number returned from the validated address.
"123" in "123 S. Main Street" 

StreetNameFragment

String

Varies

The parsed street name fragment returned from the validated address.
"Main" in "123 S. Main Street" 

StreetTypeFragment

String

Varies

The parsed street type returned from the validated address
"Street" in "123 S. Main Street" 

DirectionalCodeFragment

String

Varies

The parsed returned directional code fragment from the validated address.
"S" in "123 S. Main Street" 

UnitTypeFragment

String

Varies

The parsed unit type fragment from the validated address. i.e. "Apt" or "Suite"

UnitNumberFragment

String

Varies

The parsed unit number fragment from the validated address. "1" of "Apt 1"

IsPOBox

String

Varies

The returned Boolean value of a validated address as being a PO Box address.

BoxNumberFragmentStringVariesThe returned Box Number from a PO Box address. "1234" of "PO Box 1234"
StationInfoStringVariesThe returned Station Name of the Delivery Station.
DeliveryModeStringVariesThe returned Delivery Mode of the address.
DeliveryInstallationStringVariesThe returned Delivery Installation Type where the final mail sort happens.
CorrectionsStringVariesSee Correction Code descriptions below.
CorrectionsDescriptionsStringVariesDescription of corrections made to input address.

 

Error 

NameTypeValueDescription
TypeStringVariesThe type of error that was thrown from the service. Example: Authorization,User Input,Domain Specific
TypeCodeStringVariesThe type code of the error.  Example: 1,2,3,4,5
DescStringVariesThe description of the error that was thrown.
DescCodeStringVariesThe description code of the error that was thrown.

ValidateCanadianAddress

This operation performs basic checks on user supplied inputs; Address1, Address2, Municipality, Province or Postal Code and returns verified Address, Municipality, Province and Postal Code in Canadian address recommended format which is upper cased. This operation also returns time zone and a check on if the supplied location is a P.O. Box, General Delivery or Rural Route. This operation requires either a Postal Code or both Municipality and Province.  Providing all inputs is recommended, because it helps the validation proceed if some of the elements are malformed.

Inputs

ValidateCanadianAddress Inputs

Name

Type

Description

Address

String

Address line of the address to validate.
For example, "123 Main Street".

Address 2String

The Address2 of the address to validate. This will only be used in particular situations where the Address1 does not help in validating the address.

Municipality

String

The Municipality of the address to validate.

Province

String

The Province of the address to validate.

PostalCode

String

The Postal Code of the address to validate. A Postal Code isn't required, but if one is not provided, the Municipality and Province are required.

LicenseKey

String

Your license key to use the service.
Sign up for a free trial key at
https://www.serviceobjects.com/products/address-geocoding/canada-address-validation

Outputs

CanadianAddressResponse

All of the response objects are contained within the CanadianAddressResponse object.

NameTypeValuesDescription
CanadianAddressInfoObjectVariesThe returned values of a valid Canadian Address.
ErrorObjectVariesThe returned error result from a failed address verification or user input error.
DebugString[]VariesUsed internally for testing.

CanadianAddressInfo

Name

Type

Values

Description

Address

String

Varies

The corrected Address line 1.

Address 2StringVariesThe corrected Address line 2.

Municipality

String

Varies

The corrected Municipality.

Province

String

Varies

The corrected Province.

PostalCode

String

Varies

The corrected PostalCode.

TimeZone

String

Varies

The corresponding time zone from the validated address.

AddressNumberFragment

String

Varies

The parsed address number returned from the validated address.
"123" in "123 S. Main Street" 

StreetNameFragment

String

Varies

The parsed street name fragment returned from the validated address.
"Main" in "123 S. Main Street" 

StreetTypeFragment

String

Varies

The parsed street type returned from the validated address.
"Street" in "123 S. Main Street" 

DirectionalCodeFragment

String

Varies

The parsed returned directional code fragment from the validated address.
"S" in "123 S. Main Street" 

UnitTypeFragment

String

Varies

The parsed unit type fragment from the validated address. i.e. "Apt" or "Suite"

UnitNumberFragment

String

Varies

The parsed unit number fragment from the validated address. "1" of "Apt 1"

IsPOBox

String

Varies

The returned Boolean value of a validated address as being a PO Box address.

BoxNumberFragmentStringVariesThe returned Box Number from a PO Box address.
StationInfoStringVariesThe returned Station Name of the Delivery Station.
DeliveryModeStringVariesThe returned Delivery Mode of the address.
DeliveryInstallationStringVariesThe returned Delivery Installation Type where the final mail sort happens.

Error

NameTypeValueDescription
TypeStringVariesThe type of error that was thrown from the service. Example: Authorization,User Input,Domain Specific.
TypeCodeStringVariesThe type code of the error.  Example: 1,2,3,4,5.
DescStringVariesThe description of the error that was thrown.
DescCodeStringVariesThe description code of the error that was thrown.

ValidateCanadianMunicipalityProvince

This operation performs basic checks on user supplied inputs; Municipality, Province or Postal Code and returns verified Municipality, Province and Postal Code. This operation also returns time zone and a check on if the supplied location is a P.O. Box, General Delivery or Rural Route. This operation requires either a Postal Code or both Municipality and Province.  Providing all inputs is recommended, because it helps the validation proceed if some of the elements are malformed.

Inputs

ValidateCanadianMunicipalityProvince Inputs

Name

Type

Description

Municipality

String

Municipality to validate.

Province

String

The Province to validate.

Postal Code

String

The Postal Code to validate, which can be supplied instead of Municipality and Province to provide validated Municipality and Province.

LicenseKey

String

Your license key to use the service.
Sign up for a free trial key at
https://www.serviceobjects.com/products/address-geocoding/canada-address-validation

Outputs

CanadianAddressResponse

All of the response objects are contained within the CanadianAddressResponse object.

NameTypeValuesDescription
CanadianAddressInfoObjectVariesThe returned values of a valid Canadian Address.
ErrorObjectVariesThe returned error result from a failed address verification or user input error.
DebugString[]VariesUsed internally for testing.

CanadianAddressInfo

The response object which contains validated Canadian address information.

Name

Type

Values

Description

Address

String

Varies

No Result.

Address 2StringVaries

No Result.

Municipality

String

Varies

The corrected Municipality.

Province

String

Varies

The corrected Province.

PostalCode

String

Varies

The corrected PostalCode.

TimeZone

String

Varies

The corresponding time zone from the validated municipality province.

AddressNumberFragment

String

Varies

No Result.

StreetNameFragment

String

Varies

No Result.

StreetTypeFragment

String

Varies

No Result.

DirectionalCodeFragment

String

Varies

No Result.

UnitTypeFragment

String

Varies

No Result.

UnitNumberFragment

String

Varies

No Result.

IsPOBox

String

Varies

The returned Boolean value of a validated address as being a PO Box address.

BoxNumberFragmentStringVaries

No Result.

StationInfoStringVaries

No Result.

DeliveryModeStringVariesThe returned Delivery Mode of the Delivery Station.
DeliveryInstallationStringVariesThe returned Delivery Installation Type where the final mail sort happens.

Error

The response object returned if an error occured while processing the transaction. See error descriptions below.

NameTypeValueDescription
TypeStringVariesThe type of error that was thrown from the service. Example: Authorization,User Input,Domain Specific.
TypeCodeStringVariesThe type code of the error.  Example: 1,2,3,4,5.
DescStringVariesThe description of the error that was thrown.
DescCodeStringVariesThe description code of the error that was thrown.

ParseCanadianAddress

This operation provides address fragments based off of validated address inputs.

Inputs

ParseCanadianAddress Inputs

Name

Type

Description

Address

String

Address line of the address to parse.
For example, "123 Main Street".

Address 2String

The Address2 of the address to parse. This will only be used in particular situations where the Address1 does not help in validating the address.

Municipality

String

The Municipality of the address to parse.

Province

String

The Province of the address to parse.

PostalCode

String

The Postal Code of the address to parse. A Postal Code isn't required, but if one is not provided, the Municipality and Province are required.

LicenseKey

String

Your license key to use the service.
Sign up for a free trial key at
https://www.serviceobjects.com/products/address-geocoding/canada-address-validation

Outputs

CanadianAddressResponse

All of the response objects are contained within the CanadianAddressResponse object.

NameTypeValuesDescription
CanadianAddressInfoObjectVariesThe returned values of a valid Canadian Address.
ErrorObjectVariesThe returned error result from a failed address verification or user input error.
DebugString[]VariesUsed internally for testing.

CanadianAddressInfo

The response object which contains validated Canadian address information.

Name

Type

Values

Description

Address

String

Varies

The parsed Address line.

Address 2StringVaries

The parsed Address 2 line.

Municipality

String

Varies

The parsed Municipality

Province

String

Varies

The corrected Province.

PostalCode

String

Varies

The parsed PostalCode.

TimeZone

String

Varies

No Result

AddressNumberFragment

String

Varies

The parsed Address Number Fragment.
"123" of "123 S. Main Street" 

StreetNameFragment

String

Varies

The parsed Street Name Fragment
"Main" of "123 S. Main Street" 

StreetTypeFragment

String

Varies

The parsed Street Type Fragment.
"Street" of "123 S. Main Street" 

DirectionalCodeFragment

String

Varies

The parsed Directional Code Fragment.
"South" of "123 S. Main Street" 

UnitTypeFragment

String

Varies

The parsed Unit Type Fragment.
"Apt" or "Suite" etc 

UnitNumberFragment

String

Varies

The parsed Unit Number Fragment.
"1" of "Apt. 1" 

IsPOBox

String

Varies

No Result.

BoxNumberFragmentStringVariesThe parsed Box Number Fragment.
StationInfoStringVaries

No Result.

DeliveryModeStringVariesNo Result.
DeliveryInstallationStringVariesNo Result.

Error

The response object returned if an error occured while processing the transaction. See error descriptions below.

NameTypeValueDescription
TypeStringVariesThe type of error that was thrown from the service. Example: Authorization,User Input,Domain Specific.
TypeCodeStringVariesThe type code of the error.  Example: 1,2,3,4,5
DescStringVariesThe description of the error that was thrown.
DescCodeStringVariesThe description code of the error that was thrown.


Errors

There are four error types described below. 

Error Types

Type

TypeCode

Billable

Standard for all Gen2 Web Services

Authorization

1

No

Yes

User Input

2

No

No

Service Objects Fatal

3

No

Yes

Domain Specific

4

Yes

No

Error type 1: Authorization

These are standard to all Generation 2 DOTS Web Services.

DescCode

Description

0

Unknown authorization error.

1

Please provide a valid license key for this web service.

2

The daily allowable number of transactions for this license key has been exceeded.

3

The monthly allowable number of transactions for this license key has been exceeded.

4

The total allowable number of transactions for this license key has been exceeded.

5

There are not enough transactions available.  Check your daily/monthly transaction limits.

6

This license key has not yet been activated.

7

This license key has expired.

8

Your license key does not work on this service.

Error type 2: User Input

These errors occur as a result of bad input.  DOTS AVCA2 requires all three inputs to be present in order for a proper validation to take place.

DescCode

Description

1

Please provide a valid street address.

2

Please input either zip code or both municipality and province.

Error type 3: Service Objects Fatal

The Desc will always be the same and the DescCode has no meaning.  This is standard to all Generation 2 DOTS Web Services.  This signals an issue within the application, or a Network/Connectivity issue.

DescCode

Description

1

Unhandled error.  Please contact Service Objects.

Error type 4: Domain Specific

DescCode

Description

1

Address not found.

2

This is not a valid P.O. Box for this area.

3

Street address number not found.

4

Invalid Address.
5Municipality/Province not found.
6Multiple Postal Codes exist.

DeliveryMode Designations

A delivery mode refers to the methods by which customers receive their mail. Below are the standard abbreviations used by the service. 

AbbreviationDescription
GDGeneral Delivery
POPostal Box
RRRural Route
SSSuburban Services
MRMobile Route
LCRLetter Carrier Route
CFCall For
DIRDirect

Correction Code Designations

CodeDescription
1STREET_NAME_CORRECTION
2STREET_DIRECTIONAL_CORRECTED
3STREET_DIRECTIONAL_APPENDED
4STREET_SUFFIX_CORRECTED
5STREET_SUFFIX_APPENDED
6MUNICIPALITY_NAME_CORRECTION
7MUNICIPALITY_NAME_APPENDED
8PROVINCE_NAME_CORRECTION
9PROVINCE_NAME_APPENDED
10POSTAL_CODE_CORRECTION
11POSTAL_CODE_APPENDED


Frequently Asked Questions

I have an Address 3 element. What should I do with it?

We currently don't support any handling of the Address3 field. Passing it in as part of either the Address1 or Address2 fields is not recommended, as it may inhibit validation.

Does Address Validation Canada 2 provide support for French addresses?

Yes, this service will accept French addresses, however all output fields will be standardized to their English versions.  This service is primarily for correcting, validating and standardizing Canadian addresses.  The current Canadian standard is English, and we convert the addresses to English to provide the most accurately standardized addresses possible.  It is likely that we will add more support in the future for outputting addresses in standardized French formats as well in the future, however the rules for doing so are not as clear potentially leading to more inaccuracies in the result.

The Sample Code is giving strange errors or is crashing?

Most likely, the sample code cannot connect to Service Objects. Many environments will not allow you to connect out on port 80, or will clip out XML data from these requests/responses. 
The easiest way to check for this is to open a browser on the machine running the sample code. In your browser, navigate to:
https://trial.serviceobjects.com/avca2/api.svc
Then try to run one of the operations with your trial key. If you get a browser error, or get no data back, then the sample code isn't able to connect either. Contact your systems administrator to resolve why you are not able to connect to Service Objects.

Address Validation Canada 2 says it can't find my street!

DOTS Address Validation Canada doesn't know about every address, especially empty lots or new streets. Often, it won't be able to validate these locations. In general, we are as good as the CPC at identifying addresses.

Does Address Validation Canada 2 do delivery point validation? I need to know if CPC can deliver to this address.

Not at this time. This feature is not implemented within our system. Our system contains over 2 million Canadian addresses which are validated to CPC standards.

What are the possible errors that AVCA2 will return if an address is invalid?

Please refer to "Error Codes" above.

I need to know exactly how long each of the output fields could be. What is your standard field length?

Please email us at support@serviceobjects.com, and we'll send you the exact field length specifications. As a general rule, you won't get a field longer than 80 characters.

I'm not a programmer. How do I use DOTS Address Validation Canada 2

Service Objects runs batches for you! A free batch trial is available at
https://www.serviceobjects.com/batch/upload.

Conclusion

Service Objects is proud to offer you a free trial of DOTS Address Validation - CA.

Other technical questions or concerns can be directed to support@serviceobjects.com.

If you are interested in purchasing DOTS Address Validation - CA, please contact sales@serviceobjects.com.


  
We want to hear from you! We're always looking to improve our developer guides. 
Please email your suggestions to devguidefeedback@serviceobjects.com.

  • No labels