Introduction

DOTS Address Validation CA (AVCA) 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.
AVCA can provide instant address verification and correction to websites or enhancement to contact lists. However, the output from AVCA must be considered carefully before the existence or non-existence of an address is decided.

Integration

Integrating AVCA 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/address-validation-canada-legacy 

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. Emailsupport@serviceobjects.comfor 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:
http://trial.serviceobjects.com/avca/ValidateCanada.asmx

The location of the WSDL, or Web Service Definition Language document, is here (This is also accessible via the “Service Definition” link.):
http://trial.serviceobjects.com/avca/ValidateCanada.asmx?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.

ValidateCanadianMunicipalityProvince – validates municipality, province, and or postal code and returns verified municipality, province, and postal code as well as other metadata.
ParseCanadianAddress – validates a Canadian address and returns address fragments.
ValidateCanadianAddress – validates an address’s authenticity, and returns corrected address information for a given Canadian postal address.
ValidateCandianAddressWithExtras (recommended) – validates an address’s authenticity, and returns corrected address information for a given Canadian postal address. This includes Address 2 field for other important information.

Each of these operations will be described in detail later in this document.

Operation Definitions

This document defines the input, output and behavior of the web service operations in AVCA. Each operation has its own unique behavior and output, although some of the operations are very similar.

Important Note!
Address Validation Canada performs address correction by ensuring addresses are valid according to Canadian Postal Code. Users should review which operation will best handle their needs.

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

ValidateCanadianMunicipalityProvince Inputs

NameTypeDescription
MunicipalityStringMunicipality to validate
ProvinceStringThe Province to validate
Postal CodeStringThe Postal Code to validate, which can be supplied instead of Municipality and Province to provide validated Municipality and Province.
LicenseKeyStringYour license key to use the service.
Sign up for a free trial key at
www.serviceobjects.com.

ValidateCanadianMunicipalityProvince Outputs

NameTypeValuesDescription
MunicipalityStringVariesThe corrected Municipality
ProvinceStringVariesThe corrected Province.
PostalCodeStringVariesThe corrected PostalCode
TimeZoneStringVariesThe corresponding time zone with the verified location
IsPOBoxStringBooleanProvides a Boolean response if the Postal Code matches a P.O. Box
Error – DescStringVariesIf there was an internal web service error, the description will be displayed here.
Error – NumberString1, 2, 3, 4, 5See “Error Codes” below.
Error – LocationStringAlways nullDeprecated, no longer used.

ParseCanadianAddress

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

ParseCanadianAddress Inputs

NameTypeDescription
AddressStringAddress line of the address to validate.
For example, “123 Main Street”.
MunicipalityStringThe Municipality of the address to parse and provide address fragments.
ProvinceStringThe Province of the address to validate and provide address fragments
PostalCodeStringThe Postal Code of the address to validate. A zip code isn’t required, but if one is not provided, the Municipality and Province are required.
LicenseKeyStringYour license key to use the service.
Sign up for a free trial key at
www.serviceobjects.com.

ParseCanadianAddress Outputs

NameTypeValuesDescription
AddressStringVariesThe corrected Address line
MunicipalityStringVariesThe corrected Municipality
ProvinceStringVariesThe corrected Province
PostalCodeStringVariesThe corrected Postal Code
TimeZoneStringVariesThe corresponding Time Zone for the corrected address.
AddressNumber FragmentStringVariesThe address number fragment returned from the validated address.
StreetNameFragmentStringVariesThe street name fragment returned from the validated address.
StreetTypeFragmentStringVariesThe street type fragment returned from the validated address.
DirectionalCode FragmentStringVariesThe directional code fragment returned from the validated address.
UnitTypeFragmentStringVariesThe unit type fragment returned from the validated address.
Error – DescStringVariesIf there was an internal web service error, the description will be displayed here.
Error – NumberString1, 2, 3, 4, 5See “Error Codes” below.
Error – LocationString
Always null
Deprecated, no longer used.

ValidateCanadianAddress

This operation returns corrected address information for a given Canadian postal address

ValidateCanadianAddress Inputs

NameTypeDescription
AddressStringAddress line of the address to validate.
For example, “123 Main Street”.
MunicipalityStringThe Municipality of the address to validate.
ProvinceStringThe Province of the address to validate.
PostalCodeStringThe 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.
LicenseKeyStringYour license key to use the service.
Sign up for a free trial key at
www.serviceobjects.com.

ValidateCanadianAddress Outputs

NameTypeValuesDescription
AddressStringVariesThe corrected Address line 1.
MunicipalityStringVariesThe corrected Municipality.
ProvinceStringVariesThe corrected Province.
PostalCodeStringVariesThe corrected PostalCode.
TimeZoneStringVariesThe corresponding time zone from the validated address.
AddressNumberFragmentStringVariesThe fragment address number returned from the validated address.
StreetNameFragmentStringVariesThe street name fragment returned from the validated address.
StreetTypeFragmentStringVariesThe street type fragment returned from the validated address
DirectionalCodeFragmentStringVariesThe returned directional code fragment from the validated address.
UnitTypeFragmentStringVariesThe returned unit type fragment from the validated address.
UnitNumberFragmentStringVariesThe returned unit number fragment from the validated address.
IsPOBoxStringVariesThe returned Boolean value of a validated address as being a PO Box address.
Error – DescStringVariesIf there was an internal web service error, the description will be displayed here.
Error – NumberString1, 2, 3, 4, 5See “Error Codes” below.
Error – LocationStringAlways nullDeprecated, no longer used.

ValidateCanadianAddressWithExtras

Returns parsed and validated address elements including address line 2.

ValidateCanadianAddressWithExtras Inputs

NameTypeDescription
AddressStringAddress line of the address to validate.
For example, “123 Main Street”.
Address2StringThe Address2 of the address to validate. This will only be used in particular situations where the Address1 does not help in validating the address.
MunicipalityStringThe Municipality of the address to validate.
For example, “Vancouver”. The Municipality isn’t required, but if one is not provided, the Postal Code is required.
ProvinceStringThe Province of the address to validate. For example, “BC”. This does not need to be contracted; full Province names will work as well. The Province isn’t required, but if one is not provided, the Postal Code is required.
PostalCodeStringThe 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.
LicenseKeyStringYour license key to use the service.
Sign up for a free trial key at
www.serviceobjects.com.

ValidateCanadianAddressWithExtras Outputs

NameTypeValuesDescription
AddressStringVariesThe corrected Address line 1.
Address2StringVariesThe corrected Address line 2.
MunicipalityStringVariesThe corrected Municipality name.
ProvinceStringVariesThe corrected Province name.
Postal CodeStringVariesThe corrected Postal Code.
TimeZoneStringVariesThe corresponding time zone returned from the corrected address.
AddressNumberFragmentStringVariesThe address number fragment returned from the parsed out address.
StreetNameFragmentStringVariesThe street name fragment returned from the parsed out address.
StreetTypeFragmentStringVariesThe street type fragment returned from the parsed out address.
DirectionalCodeFragmentStringVariesThe directional code fragment returned from the parsed out address.
UnitTypeFragmentStringVariesThe unit type fragment returned from the parsed out address.
UnitNumberFragmentStringVariesThe unit number fragment returned from the parsed out address.
IsPOBoxStringVariesReturns a Boolean value if the address is a P.O. Box
Error – DescStringVariesIf there was an internal web service error, the description will be displayed here.
Error – NumberString1, 2, 3, 4, 5See “Error Codes” below.
Error – LocationStringAlways nullDeprecated, no longer used.
*Possible values/descriptions listed below.

Errors

Error codes in DOTS Address Validation CA are the same for all operations. They are as follows:

Error Number 1 — “Input cannot be less than zero length”
This error means the web service did not get any input. The connection to the service was made, and data was transferred, but no parameters were passed that the service could understand.
This error often happens when input is passed to the service with namespaces that the service does not understand. Applying a namespace to any of the parameters (Address, Municipality, Province, etc.) will cause this error. Additionally, requests made in the “rpc/encoded” format will cause this error. The only namespace that should appear in any element is the “http://www.serviceobjects.com” namespace on the root Validate* element as so:
<ValidateCanadianAddress xmlns=”https://www.serviceobjects.com/”>

Important Note!
The namespace is not applied to the ValidateCandianAddress element, it is only present.*

Error Number 2 — Various descriptions
This error code appears when various errors occur, but are of the expected nature. Oftentimes, maligned or incomplete input will cause an error 2.
The following is a list of the possible Error Descriptions that may accompany an Error Code 2:

Bad or Incomplete Addresses Errors:

Failed Authentication Errors:

Web Service Invocation Errors:

Error Number 3/4/5 — Various descriptions
An error code 3, 4, or 5 is a fatal error and it means something serious has gone wrong. You will never see one of these error codes in a live production environment.

Frequently Asked Questions

Which operation should I use?

Picking which operation you want to use should be decided carefully. Depending on your environment and needs, you will need to use different operations for their corresponding strengths.
If you only want to standardize your address you could use our “ParseCanadianAddress” operation. If you have an Address2 field, you can use any operation with the proper input. See the question below for more information.

I have Address 2 elements. What should I do?

You can either switch operations, or you can concatenate your Address2 data onto your Address1 line, separated by a comma. The operation will interpret everything after the comma as secondary address information.
If you need fragment elements, it is highly recommended that you use ValidateCandianAddress or ValidateCanadianAddressWithExtras.

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.

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:
http://trial.serviceobjects.com/avca/ValidateCanada.asmx
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 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 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 AVCA will return if an address is invalid?

Please refer to “Error Codes”, above.

What does “Multiple P.O Boxes” mean? How do I get a single result?

“Multiple PO Boxes Match” means that AVCA found multiple P.O. Boxes due to a bad postal code. Because the postal code is incorrect there is no way to distinguish multiple P.O. Boxes.

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

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.

Sign up today for a free trial at:
https://www.serviceobjects.com/products/address/address-validation-can

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 welcome your feedback! Please do not hesitate to let us know what you think of our web services, documentation, or customer support.