When Service Objects talks about address validation, we tend to focus on our US and International products, while our Canadian address validation product tends to get less attention. So I thought it was time to shine the spotlight on Address Validation – Canada, with an overview of the service, focusing on its strengths and features that make it a powerful address checking API for Canadian addresses.
The features you can find in this service are best described as follows:
- Parsing
- Municipality validation
- Address validation
- English and French output formatting
- Canada Post formatting standards
- Address normalization and standardization
- 90ms average response time
- Over 15.7 million Canadian addresses and counting
- Address fragments
- Time Zone
- Delivery Modes
- Corrections
Three operations for Address Validation – Canada
There are three main operations found in Address Validation – Canada:
- ParseCanadianAddress
- ValidateCanadianMunicipalityProvince
- ValidateCanadianAddressV2 (Recommended)
This blog will briefly go over the first two, but the main focus will be on the third, ValidateCanadianAddressV2, which we find meets the majority of our customers’ needs.
ParseCanadianAddress
Taken from our developer guides, this operation will parse out the input address into its fragments like street number, street name, unit number, etc. This operation doesn’t focus on whether an address is valid because its primary purpose is to parse out the address into its parts.
ValidateCanadianMunicipalityProvince
This operation performs basic checks on the user-supplied inputs of Municipality, Province or Postal Code, and returns verified Municipality, Province and Postal Code values. This operation also returns the time zone and performs a check to see 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. The purpose is to validate at the Municipality level and not at the address level.
ValidateCanadianAddressV2
As mentioned earlier, ValidateCanadianAddressV2 is our recommended operation. It performs validation checks on the user-supplied inputs; Address1, Address2, Municipality, Province or Postal Code. It returns verified Address, Municipality, Province and Postal Code in Canada Post’s recommended format, which is uppercased. The output can also return proper-case to the language being targeted (English or French).
We also return the output, DeliveryMode, with the response from the operation to give our clients better visibility into the kind of delivery the address is being serviced by. Some of the values for this field are General Delivery, Postal Box, Rural Route and many more.
When our system can determine the correct address from the inputs, we let you know what we fixed. We return Corrections that can be processed by a computer as well as CorrectionDescriptions that can be more easily referenced by humans. Some of the descriptions you’ll see are items such as STREET_NAME_CORRECTION, for instances where typos occurred, or STREET_DIRECTIONAL_CORRECTED, where we corrected East to West, or POSTAL_CODE_APPENDED, when we were able to fill in the missing postal code. These are just a few examples of the CorrectionDescriptions that the operation returns. You can see the complete list of Delivery Mode and Correction Codes here.
When an address is not found or fixable, the operation returns an error code with a corresponding description of what happened. For instance, if the operation could not find the address in our system it would return the DescCode 1, which would translate to an “Address not found” error. Similarly, it would return DescCode 3 for a “Street address number not found” error.
We have several errors that can give you a hint as to what needs fixing, which in turn allows organizations to recall the address and get an update from their clients or users. Additionally, it helps keep organizations from wasting time, money and other resources on sending materials that will end up not getting to the right people, or just simply returned or thrown away.
Inputs
The inputs to this operation are Address, Address2, Municipality, Province, Postal Code, Language and LicenseKey. Most of these inputs are going to be obvious, so we’ll focus on a couple of less obvious things to be aware of.
First, you don’t need every field to be able to use our address checking API and perform a validation. If you have Municipality and Province but not the Postal Code, or if you have the Postal Code but not the Municipality and Province, we can generally still validate the address. With that said, the more information you provide, the higher the likelihood we will be able to make corrections and validations.
Next, let’s look at the Language input field. This field directs the operation as to which language to return the addresses in. 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.
The last bit to be aware of is the LicenseKey input field. When organizations are evaluating our service, they often get a trial key. This key works for all the operations and any new operations that are added later. Another point to make here is that when clients create a prototype or set up a test integration with the trial key and trial endpoint, it is simple to switch to the live or production endpoint. The only other thing you will need to update in your code or integration is switching to your production License Key.
Outputs
We looked at some of the outputs of this operation above like the DeliveryMode and Corrections, but there are also several other great data points to be returned.
The operation returns the main address components back in the response from the validation. These are critical and not to be ignored even when the input address is valid. The reason is that we return corrected and standardized addresses and this will allow organizations to keep a clean and standardized database of records.
TimeZone can be an important field depending on the purposes of your validation. For example, if part of your sales or customer support efforts includes outbound calling, you can use the time zone data to help target when you reach out to contacts. It may be a little less obvious, but if you have emails instead of phone numbers in this scenario, you could target sending out emails at times that would be most advantageous for your email campaign as a marketer.
We touched on address fragments in the ParseCanadianAddress operation section, and those outputs are also included with this operation.
Ways to integrate Address Validation – Canada
The most common ways organizations integrate with our services is by plugging our address checking API into forms on websites and internal processes using custom code. When it comes to custom code, we have you covered: we have sample code for most major programming languages to help with your integration. If you need something we don’t have, just reach out to our support team, and there is a good chance we can put it together quickly for you. Need a plugin to a third-party platform like Salesforce or Marketo? Let us know and we can typically put that together for you too.
Often, when organizations sign up with us they have an existing data set that they have been collecting over months or years that they need to do an initial data cleanse on. In that situation, they will typically send us a file that we process and then they reload into their database, or they create an internal process to loop through their records and simply call our API. Some clients need batches of records processed periodically, in this case, they can upload data to our automated system, which will pick up the files, process the records and return the validated results.
You also can always go to our website and quick look-ups, or download our Data Tumbler, which acts like a spreadsheet that can validate rows and handle up to 5,000 addresses.
The beauty with our services, including our Address Validation – Canada service, is that you can fully integrate with our API before spending a dime, and with minimal effort, you can switch to the production endpoint and license key and you’re done.
For additional assistance, you can reach out to us or walk through our developer’s guide to help you with the service.
