The Location Hub® Address Suggest Service provides on-the-fly data matching, saving you time and money while dramatically improving data accuracy throughout your entire operation.

What Does It Do?

The service provides “auto-completion” capability for freeform address entry, which can be quickly integrated into any process used to capture address information, such as a web application. The service predicts the possible addresses that match the input as it is being entered by a user. Only addresses validated within the DMTI Master Address Repository are returned, minimizing the risk of keying errors or an invalid address being submitted.

Address Suggest is not a replacement for Address Recognition. It is designed to complement it in interactive applications by providing “type-ahead” or “auto-completion” capability for freeform address entry. When used in combination with Address Recognition, any text entered by the user, even when Address Suggest does not return any results, should still be run through Recognition, since it has more sophisticated methods of searching for addresses and provides some distinct capabilities not available in Address Suggest. In many cases, Address Recognition service will be able to find a match.

Accessing the Service

To access the Location Hub Address Suggest service you must first be authorized for use with Location Hub Web Services in order to have a valid user name and password. Please contact info@dmtispatial.com for more information on how to register for the Location Hub Address Suggest Web Service.

Once you have a valid user name and password, please refer to the Authentication section for information on how to access the service.

SOAP Service

SOAP Operations

Address Suggest shares the SOAP endpoint with the Address Recognition service. The operation name is Suggest and the request/response types are SuggestRequest/SuggestResponse.
  • Suggest - returns a list of possible address matches

Parameters

  • request (string): – the partial address string
  • maxSuggestions (integer): – the maximum number of possible address matches to return
  • includePostalCode (optional boolean): – option to include the Postal Code in the returned possible address matches
  • returnAliases (optional boolean): – option to return the next best alias in the Alias field which will typically be a Canada Post Municipality or Neighbourhood Name

Sample SOAP SuggestRequest and SuggestResponse:

 
<!-- SuggestRequest with returnAliases set to True -->
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v2="http://www.dmtispatial.com/recognition/v2.2/">
   <soapenv:Header/>
   <soapenv:Body>
      <v2:SuggestRequest>
         <!--type: string-->
         <v2:request>5 Byng Ave Tor</v2:request>
         <!--type: int-->
         <v2:maxSuggestions>20</v2:maxSuggestions>
         <!--Optional:-->
         <!--type: boolean-->
         <v2:includePostalCode>true</v2:includePostalCode>
         <!--Optional:-->
         <!--type: boolean-->
         <v2:returnAliases>true</v2:returnAliases>
      </v2:SuggestRequest>
   </soapenv:Body>
</soapenv:Envelope>
 
<!-- SuggestResponse with Alias -->
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
   <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
      <SuggestResponse xmlns="http://www.dmtispatial.com/recognition/v2.2/">
         <ResponseItems>
            <SuggestResult MatchCount="1" Alias="5 BYNG AVE ETOBICOKE ON M9W2M5">5 BYNG AVE TORONTO ON M9W2M5</SuggestResult>
            <SuggestResult MatchCount="1" Alias="5 BYNG AVE NORTH YORK ON M2N0E6">5 BYNG AVE TORONTO ON M2N0E6</SuggestResult>
            <SuggestResult MatchCount="1" Alias="5 BYNG AVE SCARBOROUGH ON M1L3N5">5 BYNG AVE TORONTO ON M1L3N5</SuggestResult>
         </ResponseItems>
      </SuggestResponse>
   </s:Body>
</s:Envelope>
 
 
<!-- SuggestRequest with returnAliases set to False -->
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v2="http://www.dmtispatial.com/recognition/v2.2/">
   <soapenv:Header/>
   <soapenv:Body>
      <v2:SuggestRequest>
         <!--type: string-->
         <v2:request>5 Byng Ave Tor</v2:request>
         <!--type: int-->
         <v2:maxSuggestions>20</v2:maxSuggestions>
         <!--Optional:-->
         <!--type: boolean-->
         <v2:includePostalCode>true</v2:includePostalCode>
         <!--Optional:-->
         <!--type: boolean-->
         <v2:returnAliases>false</v2:returnAliases>
      </v2:SuggestRequest>
   </soapenv:Body>
</soapenv:Envelope>
 
<!-- SuggestResponse with no Alias -->
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
   <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
      <SuggestResponse xmlns="http://www.dmtispatial.com/recognition/v2.2/">
         <ResponseItems>
            <SuggestResult MatchCount="1">5 BYNG AVE TORONTO ON M1L3N5</SuggestResult>
            <SuggestResult MatchCount="1">5 BYNG AVE TORONTO ON M2N0E6</SuggestResult>
            <SuggestResult MatchCount="1">5 BYNG AVE TORONTO ON M9W2M5</SuggestResult>
         </ResponseItems>
      </SuggestResponse>
   </s:Body>
</s:Envelope>
 

REST Service

REST Operation:

Address Suggest also shares the REST url with the Address Recognition service. The method name is suggest :
  • suggest: – returns a list of possible address matches

Input Parameters

  • address (string): – the partial address string
  • limit (integer): – the maximum number of possible address matches to return. The service has a maximum predetermined limit of 100.
  • includePostalCode (optional boolean): – option to include the Postal Code in the returned possible address matches
  • returnAliases (optional boolean): – option to return the next best alias in the aliasSuggest field which will typically be a Canada Post Municipality or Neighbourhood Name
  • format (optional string): – the output format of the response. The options supported are json or xml. If no format is provided, the service will default to json.

Output Response

The call to the service will return an array of objects each with three fields:
  • matchCount – number of addresses that potentially match the aggregate result.
    • When matchCount == 1, you have a “leaf node” – an actual individual address that is basically guaranteed to be able to go through recognition
    • When matchCount > 1, it’s an aggregate that basically requires more input from the user.
  • suggestion – the output address text
  • aliasSuggest – the output address text with the Canada Post Municipality or Neighbourhood Name as the Municipality
    • When returnAliases == false, then aliasSuggest is Null

Example:

When the beginning of “5 Byng Ave Toronto ON” is being typed, such as “5 Byng Ave Tor”, the following will be returned:

Sample REST Request and Response:

// Request with returnAliases = true and format = json
services/rest/V2.2/suggest?address=5%20Byng%20Ave%20Toronto&limit=20&includePostalCode=true&returnAliases=true&format=json
 
// Response in json with aliasSuggest
[
      {
      "matchCount": 1,
      "suggestion": "5 BYNG AVE TORONTO ON M9W2M5",
      "aliasSuggest": "5 BYNG AVE ETOBICOKE ON M9W2M5"
   },
      {
      "matchCount": 1,
      "suggestion": "5 BYNG AVE TORONTO ON M2N0E6",
      "aliasSuggest": "5 BYNG AVE NORTH YORK ON M2N0E6"
   },
      {
      "matchCount": 1,
      "suggestion": "5 BYNG AVE TORONTO ON M1L3N5",
      "aliasSuggest": "5 BYNG AVE SCARBOROUGH ON M1L3N5"
   }
]
 
// Request with returnAliases = false and format = json
services/rest/V2.2/suggest?address=5%20Byng%20Ave%20Toronto&limit=20&includePostalCode=true&returnAliases=false&format=json
 
// Response in json with null aliasSuggest
[
      {
      "matchCount": 1,
      "suggestion": "5 BYNG AVE TORONTO ON M1L3N5",
      "aliasSuggest": null
   },
      {
      "matchCount": 1,
      "suggestion": "5 BYNG AVE TORONTO ON M2N0E6",
      "aliasSuggest": null
   },
      {
      "matchCount": 1,
      "suggestion": "5 BYNG AVE TORONTO ON M9W2M5",
      "aliasSuggest": null
   }
]
 
 
// Request with returnAliases = true and format = xml
services/rest/V2.2/suggest?address=5%20Byng%20Ave%20Toronto&limit=20&includePostalCode=true&returnAliases=true&format=xml
 
// Response in xml with aliasSuggest
<suggestions xmlns="http://schemas.datacontract.org/2004/07/ServiceRestInterface" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
   <suggestion>
      <matchCount>1</matchCount>
      <suggestion>5 BYNG AVE TORONTO ON M9W2M5</suggestion>
      <aliasSuggest>5 BYNG AVE ETOBICOKE ON M9W2M5</aliasSuggest>
   </suggestion>
   <suggestion>
      <matchCount>1</matchCount>
      <suggestion>5 BYNG AVE TORONTO ON M2N0E6</suggestion>
      <aliasSuggest>5 BYNG AVE NORTH YORK ON M2N0E6</aliasSuggest>
   </suggestion>
   <suggestion>
      <matchCount>1</matchCount>
      <suggestion>5 BYNG AVE TORONTO ON M1L3N5</suggestion>
      <aliasSuggest>5 BYNG AVE SCARBOROUGH ON M1L3N5</aliasSuggest>
   </suggestion>
</suggestions>
 
// Request with returnAliases = false and format = xml
services/rest/V2.2/suggest?address=5%20Byng%20Ave%20Toronto&limit=20&includePostalCode=true&returnAliases=false&format=xml
 
// Response in xml with nil aliasSuggest
<suggestions xmlns="http://schemas.datacontract.org/2004/07/ServiceRestInterface" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
   <suggestion>
      <matchCount>1</matchCount>
      <suggestion>5 BYNG AVE TORONTO ON M1L3N5</suggestion>
      <aliasSuggest i:nil="true"/>
   </suggestion>
   <suggestion>
      <matchCount>1</matchCount>
      <suggestion>5 BYNG AVE TORONTO ON M2N0E6</suggestion>
      <aliasSuggest i:nil="true"/>
   </suggestion>
   <suggestion>
      <matchCount>1</matchCount>
      <suggestion>5 BYNG AVE TORONTO ON M9W2M5</suggestion>
      <aliasSuggest i:nil="true"/>
   </suggestion>
</suggestions>