DOTS Address Validation CA

• Introduction
• Integration
• Web Service Structure
• Operation Definitions
  • ValidateCanadianMunicipalityProvince
  • ParseCanadianAddress
  • ValidateCanadianAddress
  • ValidateCanadianAddressWithExtras
• Errors
• Frequently Asked Questions
• Conclusion

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/sample-code/?service=71 

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.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:
https://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.):
https://trial.serviceobjects.com/avca/ValidateCanada.asmx?WSDL

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.

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

ValidateCanadianMunicipalityProvince Outputs

ParseCanadianAddress

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

ParseCanadianAddress Inputs

ParseCanadianAddress Outputs

ValidateCanadianAddress

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

ValidateCanadianAddress Inputs

ValidateCanadianAddress Outputs

ValidateCanadianAddressWithExtras

Returns parsed and validated address elements including address line 2.

ValidateCanadianAddressWithExtras Inputs

ValidateCanadianAddressWithExtras Outputs

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 “https://www.serviceobjects.com” namespace on the root Validate* element as so:
<ValidateCanadianAddress xmlns=”https://www.serviceobjects.com/”>

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:

• “Could nor parse address”
• “Address does not appear to be valid”
• “This is not a valid P.O. Box for this area “
• “No results found”
• “Multiple P.O. Boxes match. Bad Postal Code.”
• “The street number you entered is not valid for the given street.”

Failed Authentication Errors:

• “Please provide a valid license key for this web service.”
• “The daily allowable number of transactions for this license key has been exceeded.”
• “The monthly allowable number of transactions for this license key has been exceeded.”
• “The total allowable number of transactions for this license key has been exceeded.”
• “There are not enough transactions available. Check your daily/monthly transaction limits.”
• “This license key has expired.”
• “This license key has not yet been activated.”
• “This operation is limited to specific usage. Please contact customer service to have your key enabled.”
• “Your license key does not work on this service.”

Web Service Invocation Errors:

• “Error initializing service”
• “Please input a street address”
• “Please input either zip code or both municipality and province”
• “Input can not be less than zero length (Address, Municipality, Province, PostalCode, LicenseKey)” 
• “Multiple addresses match” means that there was an ambiguity about the address, most likely having to do with the street directional. Often, if there is a “West Main St” and an “East Main St” in a given location, trying to validate just “Main St” will give a “multiple addresses match” error.

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:
https://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/upload-center/.

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/address-validation/?canada

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.