Download the Canada Post Mobile App for: Apple | Android Français

AddressComplete Interactive Find (v2.10)

Find addresses matching the search term.

REST code samples & endpoints

Choose a code sample language below.

Select an endpoint to view an example.

Try it

Enter your values in the form below to try the service for yourself. We've entered some example values to get you started.

Name Value Type Default Description
SearchTerm * String The search term to find. If the LastId is provided, the SearchTerm searches within the results from the LastId.
LastId String The Id from a previous Find or FindByPosition.
SearchFor String Everything Filters the search results.
Country String CAN The name or ISO 2 or 3 character code for the country to search in. Most country names will be recognised but the use of the ISO country code is recommended for clarity.
LanguagePreference String en The 2 or 4 character language preference identifier e.g. (en, en-gb, en-us etc).
MaxSuggestions Integer 7 The maximum number of autocomplete suggestions to return.
MaxResults Integer 100 The maximum number of retrievable address results to return.

* Required

Parameters

Each request to the web service requires the following parameters. You can create any number of keys, each of which can be reported on individually and have specific security settings.

Name Type Description Default Example
Key * String The key to use to authenticate to the service. AA11-AA11-AA11-AA11
SearchTerm * String The search term to find. If the LastId is provided, the SearchTerm searches within the results from the LastId. 2701 ri
LastId String The Id from a previous Find or FindByPosition.
SearchFor String Filters the search results. Everything Everything
Country String The name or ISO 2 or 3 character code for the country to search in. Most country names will be recognised but the use of the ISO country code is recommended for clarity. CAN CAN
LanguagePreference String The 2 or 4 character language preference identifier e.g. (en, en-gb, en-us etc). en EN
MaxSuggestions Integer The maximum number of autocomplete suggestions to return. 7 7
MaxResults Integer The maximum number of retrievable address results to return. 100 7

Fields

The response from the web service is a table containing the elements below. Where no items are found, the response will be empty (although all endpoints specify the columns). If an error occurs, the response will be an error table instead. (See response errors and general errors below.)

Name Type Description Values Example
Id String The Id to be used as the LastId with the Find method.
CAN|PR|X247361852|E|0|0
Text String The found item.
2701 Riverside Dr, Ottawa, ON
Highlight String A list of number ranges identifying the characters to highlight in the Text response (zero-based start position and end).
0-2,6-4
Cursor Integer A zero-based position in the Text response indicating the suggested position of the cursor if this item is selected. A -1 response indicates no suggestion is available.
0
Description String Descriptive information about the found item, typically if it's a container.
102 Streets
Next String The next step of the search process.
  • Find
  • Retrieve
Retrieve

Response Errors

Below are the errors specific to this web service (general errors are listed following these). If an error occurs, an error table like the one below (but containing a single row) will be returned. (Developers should test for a 4-column table with columns "Error", "Description", "Cause" and "Resolution".)

Error Description Cause Resolution
1001 SearchTerm or LastId Required The SearchTerm or LastId parameters were not supplied. Check they were supplied and try again.
1002 SearchFor or LastId Invalid The SearchFor or LastId parameter was not recognised. Check the documentation for valid options.
1003 Country Invalid The Country parameter was not recognised. Check the spelling and, if in doubt, use a valid ISO 2 or 3 digit country code. Provide a valid ISO 2 or 3 digit country code or use a web service to convert country name to ISO code.
1004 LanguagePreference Invalid The LanguagePreference parameter was not recognised. Please check what you entered and try again.
1005 No response The query didn't respond fast enough, it may be too complex. Please check what you entered and try again with something more specific.

General Errors

These errors are general service errors and can be returned by any web service. Note that general errors are all below 100 while service-specific errors start at 1000.

Error Description Cause Resolution
-1 Unknown error The cause of the error is unknown but details have been passed to our support staff who will investigate. These problems are typically short lived and are often resolved by trying again in a few minutes.
2 Unknown key The key you are using to access the service was not found. Please check that the key is correct. It should be in the form AA11-AA11-AA11-AA11.
3 Account out of credit Your account is either out of credit or has insufficient credit to service this request. Please check your account balance and top it up if necessary.
4 Request not allowed from this IP The request was disallowed from the IP address. Check the security settings on the key first. If they look fine, please contact support as it may be from an IP address on our blacklist.
5 Request not allowed from this URL The request was disallowed from the URL. Check the security settings on the key first. If they look fine, please contact support as it may be from a URL on our blacklist.
6 Web service not available on this key The requested web service is disallowed on this key. Check the security settings on the key first. You can limit a key to certain web services.
7 Web service not available on your plan The requested web service is not currently available on your payment plan. Some services are only available in specific regions due to licensing restrictions. Please contact us for more information.
8 Key daily limit exceeded The daily limit on the key has been exceeded. Alter the daily limit on the key. Check the usage details first to see if usage is normal.
9 Your account has been suspended Your account has been suspended. This can be for a number of reasons including non-payment of an invoice. Please contact us in order to resolve this issue.
10 Surge protector triggered An unusually large number of requests have been processed for your account so the surge protector has been enabled. You can disable the surge protector at any time but this is only recommended if you are running through a batch of requests.
11 No valid license available The request requires a valid license but none were found. Please check your purchase history. You may be using a license that is no longer valid or of an incorrect type.
12 Management key required To use this web service you require a management key. Management can be enabled on any key, but we advise you to use management keys with care. Sign in to the website and create a new management key or change an existing key.
13 Demo limit exceeded The daily demonstration limit for this service or account has been exceeded. The limit will be reset at midnight tonight. If you would like the limit increased, please contact us.
14 Free service limit exceeded You have used too many free web services. Our web services are designed to operate in stages. The first is usually a Find service followed by a Retrieve. If you use too many Finds without the corresponding number of Retrieves you will receive this error. For more information, please contact us.
15 Wrong type of key The type of key you're using isn't supported by this web service. This usually happens if you're using a user or server license with a web service that only supports transactional keys. Please use another key and try again.
16 Key expired The key you are trying to use has expired. Please check that you are using the right key. A new one may have been issued if you recently renewed your key. Contact us if you have any questions.
17 Key daily limit exceeded The daily limit on the key has been exceeded. Alter the daily limit on the key. Check the usage details first to see if usage is normal.
18 Missing or invalid parameters A required parameter was not supplied of the value of a parameter cannnot be converted into the right type. Check the parameters passed and their values against the specification for this service.
19 Invalid JSON object The JSON object sent in your request is invalid. Please ensure your JSON object is syntactically correct and try again.
20 Endpoint not available The web service you are calling is not available on this endpoint Refer to our documentation pages to ensure you are calling a valid endpoint for the web service you are requesting.
21 Sandbox Mode is not available on this endpoint The License key used has Sandbox Mode enabled, but the testing functionality is not available on this endpoint. Disable the Sandbox Mode on the License key.
22 HTTPS requests only As of 3rd September 2018 all new accounts must use HTTPS. Ensure you consume all of our APIs over HTTPS and not HTTP.
23 Agreement Not Signed There are agreements associated with service which are not signed. Please go to your account and check your agreements.