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

AddressComplete - Web Services

Web Service Description
AddressComplete Interactive Find (v2.10) Find addresses matching the search term.
AddressComplete Interactive FindByPosition (v2.00) Find addresses near the given location.
AddressComplete Interactive Retrieve (v2.11) Returns the full address details based on the Id.

Using the AddressComplete API

The AddressComplete API is an advanced option for companies who want to implement a custom integration of AddressComplete.


Setup and API Key Creation

To create an API key:

  1. Sign in to the AddressComplete website.
  2. From the Dashboard, select Create New Installation.
  3. Select Skip setup and create an advanced API key.
  4. Enter a name for your API key. This is the name that will appear when you view your integrations/keys in your dashboard.
  5. You will be brought to a detail screen for the newly created key. Scroll down to the API key section to retrieve your key. If desired, you can also change any other settings on the key, such as valid URLs and IPs, the IP limiter and the daily limit.
  6. Navigate to the main AddressComplete website and select Support.
  7. From the left menu, select API to access the documentation you need to create a request to the AddressComplete web service.

The AddressComplete API

The following 3 methods implement AddressComplete:

  • AddressComplete Interactive AutoComplete
  • AddressComplete Interactive AutoCompleteFind
  • AddressComplete Interactive RetrieveById

API Documentation Overview

From the API page, select the name of the web service to access the documentation page for that method. Each page contains the following sections:

  1. The top section of the page contains the link to the WSDL for SOAP requests on the left and on the right, samples for all RESTful endpoints and function examples for a number of common programming languages. Choose a code sample language and then select View. The code sample will be displayed and you can copy it for use within your own calls to the service.
  2. Try it

    This section allows you to enter dummy information, simulate a test request and view the response. A Results table will appear after you select Start the test.

  3. Parameters

    This section lists the parameters (optional and required) that you need to populate when making the request.

  4. Fields

    The elements contained in the response object.

  5. Response Errors

    Error messages and their codes specific to a particular web service.

  6. General Errors

    A comprehensive list of all account and web service errors. Not specific to a particular web service method.

Using the API

All services are available over HTTP and HTTPS. The basic API model is:

AutoComplete -> AutoCompleteFind -> RetrieveById

  • AutoComplete – initiates the address lookup process and may be called one or many times.
  • AutoCompleteFind – provides more details about a given search. This method only needs to be called if the IsRetrievable flag from the results of AutoComplete is set to false. May be called zero or many times.
  • RetrieveById – returns the final address and is the only billable request in the process.

Starting a Regular Search with AutoComplete

Searching is initiated on a key press with the full SearchTerm and ISO Country set to AutoComplete. Call the method after each key press using the onkeyup event. Use caching where possible to reduce server load. The AutoComplete method will return a list of up to 8 matching objects.

Present the list to the user. The Match & Suggestion parts help indicate the progress of the search and should be concatenated, ideally with Match emboldened. If the selected Id has IsRetrievable flagged against it, pass the selected Id to RetrieveById, otherwise pass it to AutoCompleteFind.

View AutoComplete API documentation.

Starting a Location-Aware Search with AutoComplete

Searching is initiated by the AutoComplete method. The lat + long can be supplied in the Location parameter along with the LocationAccuracy (GPS error in metres) and country. The AutoComplete method will return a list of up to 8 close-by properties, streets or cities based on the LocationAccuracy supplied.

Present the list to the user. The Match & Suggestion parts help indicate the progress of the search and should be concatenated, ideally with Match emboldened. If the selected Id has IsRetrievable flagged against it, pass the selected Id to RetrieveById, otherwise pass it to AutoCompleteFind.

View AutoComplete API documentation.

AutoCompleteFind

The results of AutoCompleteFind should be presented to the user. If IsRetrievable is flagged against the selected item, the Id should be passed to RetrieveById, otherwise a subsequent call to AutoCompleteFind should be made to refine the search. Depending on the country there may be several refining steps.

Note: The AutoCompleteFind method is a critical user experience phase of the process and contains substantial optimizations. It is strongly recommended that requests are made directly from the user to the AdressComplete hosting cloud rather than through server-side requests that will add latency.

View AutoCompleteFind API documentation.

RetrieveById

RetrieveById returns the formatted address.

The results of RetrieveById are a series of FieldGroups. The Common group is populated for all countries. The Common Label formats the address in the preferred casing and styling for the selected country. The Country group contains additional properties specific to that country, e.g. UDPRN in the UK. Other groups may be present if using the AddressComplete control.

The Application should be the name of the current application whilst the CustomerId should be the Id of the address containing the object in the application. These are for future, advanced services and are optional.

View RetrieveById API documentation.