Recognition – SOAP Service

SOAP Operations

There are 4 main address recognition operations available through SOAP/XML

  • RecognizeById – finds address based on a Unique Address Identifier (UAID). This operation accepts the following parameters:
    • UAID (string)
  • RecognizeFreeForm – recognizes an entire address as a single line. This operation accepts the following parameters:
    • AddressLine (string)
  • RecognizeUnparsed – recognizes an address based on Address Line 1, Address Line 2 and separate fields for Municipality, Province, and Postal Code. This operation accepts the following parameters:
    • AddressLine1 (string)
    • AddressLine2 (string)
    • Municipality (string)
    • ProvinceState (string)
    • PostalCode (string)
    • Country (string)
  • RecognizeParsed – recognizes an address based on individual address components. This operation accepts the following parameters:
    • StreetNumber (integer)
    • StreetNumberSuffix (string)
    • StreetPreDirection (string)
    • StreetPreType (string)
    • StreetName (string)
    • StreetType (string)
    • StreetDirection (string)
    • SubAddressType (string)
    • SubAddressNumber (string)
    • Municipality (string)
    • ProvinceState (string)
    • PostalCode (string)
    • Country (string)

Options

Each Recognize SOAP/XML operation accepts Options that affect the behavior of the recognition process. The most commonly customized are:

  • ScoreThreshold: only return results with a Score at or above the ScoreThreshold
  • MaxResults: some requests (e.g. “10 KING ST” with no municipality) produce a lot of potential matches, this will limit the number of result candidates per request item.

Output

Each Recognize operation can accept one or more request items and will respond with the same number of ResponseItem collections (of type Location). A ResponseItem collection can contain:

  • 0 items: Address not recognized
  • 1 item: A single address match
  • 2 or more items: Multiple matches if the input address is ambiguous. For example; a street direction was missing in the input

The following tables summarize the descriptions and values where applicable for each of the returned data fields from the service.

Field Value type / range Description
Score float: 0.0 – 1.0 Match Score: Higher score = higher confidence of match being correct.
UAID * GUID Unique Address Identifier
RDSID integer DMTI internal use only
UUAID * GUID Unique Unit Address Identifier
CI * float: 0.0 – 1.0 Corroborative Index
Coordinate WGS84 Lat/Lon Coordinates
CoordinateType
  • Address: high precision or interpolated from road segment
  • RoadSegment: road segment centroid
  • Road: road centroid
  • PostalCode: Postal Code (FSA or FSA+LDU boundary) centroid
  • Municipality: Municipality centroid
  • Intersection: road intersection
Coordinate Type
AddressPointType
  • HighPrecision: Rooftop, entrance, driveway, parcel centroid
  • Routable: Coordinates on the road segment, usable for routing
Note:AddressPointType is an optional attribute and is only valid when CoordinateType equals to Address. All other CoordinateTypes do not represent address points, so AddressPointType would have no meaning.
PDC See PDC Table Position Determination Code
MDUFlag * True / False / Null Specifies whether the address represents a Multiple Dwelling Unit
ResidentialFlag *
  • Residential
  • NonResidential
  • Mixed (includes both residential and non-residential)
  • Null
Identifies the primary use of the address
AddressLine string Concatenated version of the address
StreetNumber integer Street Number
StreetNumberSuffix string Street Number Suffix
StreetPreDirection string Prefix Street Direction
StreetPreType string Prefix Street Type
StreetName string Street Name
StreetType string Street Type
StreetDirection string Street Direction
Municipality string Municipality (official Census municipality)
PostalMunicipality string Mailing Municipality
StateProvince string Province
PostalCode string Postal Code
Country string Country
Change Flag See Change Flag details below Each address element that was changed will have an attribute providing the change description.
DA string Statistics Canada Census Dissemination Area Identifier
UsedMunicipalityAlias string The recognized Municipality alias for the Municipality in the response

Change flags: the ChangeFlag attribute in the response can be used to provide feedback to an application user about which address elements changed in the output vs input (by the means of e.g. displaying input and output address lines side by side and highlighting the corrected elements in the output. See the examples below). The values are:

  • Changed – element was present in the input, and was replaced with corrected value (St -> Ave, N -> S, Toronto -> Markham, etc.)
  • Ignored – element was present in the input but wasn’t needed (15 Allstate Pkwy South Markham -> 15 Allstate Pkwy Markham)
  • Added – element was missing (15 Allstate Markham -> 15 Allstate Pkwy Markham)
  • Standardized – element was changed to its standard form. This includes usage of aliases (15 Allstate Parkway -> 15 Allstate Pkwy).
  • AliasUsed – applies when alternative name was used to recognize municipality or street name (666 Burnhamthorpe Rd Etobicoke -> 666 Burnhamthorpe Rd Toronto).
  • FuzzyUsed – spelling of a street or municipality name was corrected (15 Alstate Pkwy Markham -> 15 Allstate Pkwy Markham)

*While Location Hub Services will return such values as UAID/UUAID, CI, MDU and Residential flags, the client may not be licensed to use the values. Please make sure the client is appropriately licensed to use these values.