Location Hub (+)

Address Assert (+)

Address Recognition (+)

Address Suggest

Authentication (+)

Elevation Service

File Management Service

Flood Service (+)

Point in Polygon Service

Proximity Service

Reverse Geocode

Location Hub Viewer (+)

Address Suggest

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.comfor 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 Operations

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.
  • provinceFilter (optional string): – option to filter results by Province. This parameter accepts a comma separated list of abbreviated Provinces and Territories: AB,BC,MB,NB,NL,NS,NT,NU,ON,PE,QC,SK,YT
  • sortByMunicipality (optional boolean): – option to sort by Municipalities with the largest population first
  • lat (optional decimal): – option to sort by proximity to a location based on Latitude and Longitude coordinates. This parameter accepts valid Latitude values.
  • lon (optional decimal): – option to sort by proximity to a location based on Latitude and Longitude coordinates. This parameter accepts valid Longitude values.

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>
 
// Request with provinceFilter=MB,SK and sortByMunicipality=true
services/rest/V2.2/suggest?address=123 Main St W&limit=50&includePostalCode=true&returnAliases=true&format=json&provinceFilter=MB,SK&sortByMunicipality=true
 
// Response in json sorted by Populated Municipalities and filtered for MB and SK
[
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W WARMAN SK S0K0A1",
        "aliasSuggest": "123 MAIN ST W WARMAN SK S0K0A1"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W LANGHAM SK S0K2L0",
        "aliasSuggest": "123 MAIN ST W LANGHAM SK S0K2L0"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W NEEPAWA MB R0J1H0",
        "aliasSuggest": "123 MAIN ST W NEEPAWA MB R0J1H0"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W GREY MB R0G0W0",
        "aliasSuggest": "123 MAIN ST W HAYWOOD MB R0G0W0"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W CHRISTOPHER LAKE SK S0J0N0",
        "aliasSuggest": "123 MAIN ST W CHRISTOPHER LAKE SK S0J0N0"
    }
]
 
// Request with Latitude and Longitude set to coordinates for Thunder Bay, ON
services/rest/v2.2/suggest?address=123 Main St W&limit=50&includePostalCode=true&returnAliases=true&format=json&lat=48.3818&lon=-89.2461
 
// Response sorted by proximity to Thunder Bay, ON
[
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W GREATER SUDBURY / GRAND SUDBURY ON P0M1L0",
        "aliasSuggest": "123 MAIN ST W CHELMSFORD ON P0M1L0"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W GREY MB R0G0W0",
        "aliasSuggest": "123 MAIN ST W HAYWOOD MB R0G0W0"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W NEEPAWA MB R0J1H0",
        "aliasSuggest": "123 MAIN ST W NEEPAWA MB R0J1H0"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W NORTH BAY ON P1B2T6",
        "aliasSuggest": "123 MAIN ST W NORTH BAY ON P1B2T6"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W GREY HIGHLANDS ON N0C1H0",
        "aliasSuggest": "123 MAIN ST W MARKDALE ON N0C1H0"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W MINTO ON N0G2P0",
        "aliasSuggest": "123 MAIN ST W PALMERSTON ON N0G2P0"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W NORTH PERTH ON N4W1A2",
        "aliasSuggest": "123 MAIN ST W LISTOWEL ON N4W1A2"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W SOUTHGATE ON L9V3K3",
        "aliasSuggest": "123 MAIN ST W SHELBURNE ON L9V3K3"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W SHELBURNE ON L9V2X8",
        "aliasSuggest": "123 MAIN ST W SHELBURNE ON L9V2X8"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W KINGSVILLE ON N9Y1H6",
        "aliasSuggest": "123 MAIN ST W KINGSVILLE ON N9Y1H6"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W NEW TECUMSETH ON L0G1A0",
        "aliasSuggest": "123 MAIN ST W BEETON ON L0G1A0"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W CHATHAM-KENT ON N0P2C0",
        "aliasSuggest": "123 MAIN ST W RIDGETOWN ON N0P2C0"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W NORWICH ON N0J1P0",
        "aliasSuggest": "123 MAIN ST W NORWICH ON N0J1P0"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W HAMILTON ON L8P1H9",
        "aliasSuggest": "123 MAIN ST W HAMILTON ON L8P1H9"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W GRIMSBY ON L3M1R9",
        "aliasSuggest": "123 MAIN ST W GRIMSBY ON L3M1R9"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W HALDIMAND COUNTY ON N1A3C8",
        "aliasSuggest": "123 MAIN ST W DUNNVILLE ON N1A3C8"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W PORT COLBORNE ON L3K3V3",
        "aliasSuggest": "123 MAIN ST W PORT COLBORNE ON L3K3V3"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W MERRICKVILLE-WOLFORD ON K0G1N0",
        "aliasSuggest": "123 MAIN ST W MERRICKVILLE ON K0G1N0"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W HAWKESBURY ON K6A2H3",
        "aliasSuggest": "123 MAIN ST W HAWKESBURY ON K6A2H3"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W CHAMPLAIN ON K0B1R0",
        "aliasSuggest": "123 MAIN ST W VANKLEEK HILL ON K0B1R0"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W CHRISTOPHER LAKE SK S0J0N0",
        "aliasSuggest": "123 MAIN ST W CHRISTOPHER LAKE SK S0J0N0"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W WARMAN SK S0K0A1",
        "aliasSuggest": "123 MAIN ST W WARMAN SK S0K0A1"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W LANGHAM SK S0K2L0",
        "aliasSuggest": "123 MAIN ST W LANGHAM SK S0K2L0"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W SAINT JOHN NB E2M3N4",
        "aliasSuggest": "123 MAIN ST W SAINT JOHN NB E2M3N4"
    }
]
back to top