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

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:
http://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

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
www.serviceobjects.com.

ValidateCanadianMunicipalityProvince Outputs

Name

Type

Values

Description

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 with the verified location

IsPOBox

String

Boolean

Provides a Boolean response if the Postal Code matches a P.O. Box

Error – Desc

String

Varies

If there was an internal web service error, the description will be displayed here.

Error – Number

String

1, 2, 3, 4, 5

See "Error Codes" below.

Error – Location

String

Always null

Deprecated, no longer used.

ParseCanadianAddress

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

ParseCanadianAddress Inputs

Name

Type

Description

Address

String

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

Municipality

String

The Municipality of the address to parse and provide address fragments.

Province

String

The Province of the address to validate and provide address fragments

PostalCode

String

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

LicenseKey

String

Your license key to use the service.
Sign up for a free trial key at
www.serviceobjects.com.

 

ParseCanadianAddress Outputs

Name

Type

Values

Description

Address

String

Varies

The corrected Address line

Municipality

String

Varies

The corrected Municipality

Province

String

Varies

The corrected Province

PostalCode

String

Varies

The corrected Postal Code

TimeZone

String

Varies

The corresponding Time Zone for the corrected address.

AddressNumber Fragment

String

Varies

The address number fragment returned from the validated address.

StreetNameFragment

String

Varies

The street name fragment returned from the validated address.

StreetTypeFragment

String

Varies

The street type fragment returned from the validated address.

DirectionalCode Fragment

String

Varies

The directional code fragment returned from the validated address.

UnitTypeFragment

String

Varies

The unit type fragment returned from the validated address.

Error – Desc

String

Varies

If there was an internal web service error, the description will be displayed here.

Error – Number

String

1, 2, 3, 4, 5

See "Error Codes" below.

Error – Location

String

Always null

Deprecated, no longer used.

ValidateCanadianAddress

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

ValidateCanadianAddress Inputs

Name

Type

Description

Address

String

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

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
www.serviceobjects.com.

ValidateCanadianAddress Outputs

Name

Type

Values

Description

Address

String

Varies

The corrected Address line 1.

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 fragment address number returned from the validated address.

StreetNameFragment

String

Varies

The street name fragment returned from the validated address.

StreetTypeFragment

String

Varies

The street type fragment returned from the validated address

DirectionalCodeFragment

String

Varies

The returned directional code fragment from the validated address.

UnitTypeFragment

String

Varies

The returned unit type fragment from the validated address.

UnitNumberFragment

String

Varies

The returned unit number fragment from the validated address.

IsPOBox

String

Varies

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

Error – Desc

String

Varies

If there was an internal web service error, the description will be displayed here.

Error – Number

String

1, 2, 3, 4, 5

See "Error Codes" below.

Error – Location

String

Always null

Deprecated, no longer used.

ValidateCanadianAddressWithExtras


Returns parsed and validated address elements including address line 2.

ValidateCanadianAddressWithExtras Inputs

Name

Type

Description

Address

String

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

Address2

String

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.
For example, "Vancouver". The Municipality isn't required, but if one is not provided, the Postal Code is required.

Province

String

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

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
www.serviceobjects.com.

ValidateCanadianAddressWithExtras Outputs

Name

Type

Values

Description

Address

String

Varies

The corrected Address line 1.

Address2

String

Varies

The corrected Address line 2.

Municipality

String

Varies

The corrected Municipality name.

Province

String

Varies

The corrected Province name.

Postal Code

String

Varies

The corrected Postal Code.

TimeZone

String

Varies

The corresponding time zone returned from the corrected address.

AddressNumberFragment

String

Varies

The address number fragment returned from the parsed out address.

StreetNameFragment

String

Varies

The street name fragment returned from the parsed out address.

StreetTypeFragment

String

Varies

The street type fragment returned from the parsed out address.

DirectionalCodeFragment

String

Varies

The directional code fragment returned from the parsed out address.

UnitTypeFragment

String

Varies

The unit type fragment returned from the parsed out address.

UnitNumberFragment

String

Varies

The unit number fragment returned from the parsed out address.

IsPOBox

String

Varies

Returns a Boolean value if the address is a P.O. Box

Error – Desc

String

Varies

If there was an internal web service error, the description will be displayed here.

Error – Number

String

1, 2, 3, 4, 5

See "Error Codes" below.

Error – Location

String

Always null

Deprecated, 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="http://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:

  • "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:
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
http://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:
http://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.

  • No labels