Recognition – REST Service

REST Service

REST Operations

There are 3 main Address Recognition operation requests available through REST

  • Find: finds an address based on a Unique Address Identifier (UAID®)
  • Recognize: recognizes an entire address as a single line
  • RecognizeFreeForm: recognizes an entire address as a single line similar to the SOAP interface. This request provides additional optional parameters and returns a complete set of output attributes similar to the SOAP interface.

For REST Batch Requests, please refer to the REST Batch Service page.

Parameters

The Find operation accepts the following parameters:

  • uaid: The Unique Address Identifier (UAID®)
  • format: the output format of the response. The options supported are json or xml. If no format is provided, the service will default to json.

The Recognize operation accepts the following parameters:

  • address: The input address as a single line
  • limit: Maximum number of candidates to return. Please note: the candidates are ordered by score (highest first).
  • scoreThreshold: only return results with a Score at or above the ScoreThreshold. Please refer to Recognition Score for more information.
  • format: the output format of the response. The options supported are json or xml. If no format is provided, the service will default to json.

The RecognizeFreeForm operation accepts the following parameters:

  • address: The input address as a single line
  • maxResults: Maximum number of candidates to return. Please note: the candidates are ordered by score (highest first).
  • scoreThreshold: only return results with a Score at or above the ScoreThreshold. Please refer to Recognition Score for more information.
  • useFuzzy: (Optional – default: true) allow inexact Street and Municipality name matching. Fuzzy matching enables recognition of slight variations of names, misspellings, etc.
  • inferSubAddresses: (Optional – default: false) set this option to return a recognized unit with UUAIDTM when the unit does not exist in the Location Hub database.
  • recognizePostalAddresses: (Optional – default: false) is available to support the recognition of a Postal Address. An example of a postal address can include P.O. Box and rural routes. This option must be set to TRUE in your request for Postal Addresses to be recognized and geocoded, however it will not have an impact when processing a civic address and as such is recommended to always be set to TRUE.
  • recognizeIntersections: (Optional – default: false) set this option to allow intersection recognition and geocoding. When input is recognized as intersection, the response will be of type LocationIntersection (rather than LocationAddress).
  • interpolatedOnly: (Optional – default: false) set this option to return interpolated coordinates only (instead of high precision coordinates when available, interpolated in other cases).
  • interpolationInset: (Optional – default: 20.0m) avoid placing the interpolated coordinates within this distance from intersections.
  • interpolationOffset: (Optional – default: 10.0m) offset the interpolated coordinates from the road centreline.
  • EnablePostalCodeExpansion: (Optional – default: false) is available to only free form or unparsed address recognition requests. When this option is enabled and a valid complete six digit postal code is submitted in the request, the response will include all civic addresses in the postal code.
  • format: the output format of the response. The options supported are json or xml. If no format is provided, the service will default to json.

The service will return a collection of zero or more matching address candidates.

The return data types for Find and Recognize are:

class Address
{
    GUID? UAID; // nullable
    GUID? UUAID; // nullable
    float score;
    Coordinates[] coordinates; // see below
    bool? MDUFlag; // nullable
    ResidentialFlag? residentialFlag; // see below
    string freeFormAddress;
    string country;
    string locale;
 
// address components
    int? streetNumber; // nullable
    string streetNumberSuffix;
    string streetName;
    string streetType;
    string streetDirection;
    string unitType;
    string unitNumber;
    string municipality;
    string postalMunicipality;
    string provinceState;
    string postalCode;
}
 
class Coordinates
{
    CoordinateType coordinateType; // see below
    AddressPointType? addressPointType; // nullable
 
    // AddressPointType is only valid when CoordinateType == Address, see below
    double lat;
    double lon;
    int PDC;
}
 
enum CoordinateType
{
    None = 0,
    Address = 1,
    RoadSegment = 2,
    Road = 3,
    PostalCode = 4,
    Municipality = 5,
    Intersection = 6,
}
 
enum AddressPointType
{
    HighPrecision = 0,
    Routable = 1,
}
 
enum ResidentialFlag
{
    Residential = 0,
    NonResidential = 1,
    Mixed = 2,
}

Example (Find request):

A request for UAID “5c2d1184-d1b5-ebc5-2d01-5d34fc18e88f” will produce the following output:

// Find REST Request:
find?uaid=5c2d1184-d1b5-ebc5-2d01-5d34fc18e88f&format=json
 
//Find REST Response:
{
   "MDUFlag": true,
   "UAID": "5c2d1184-d1b5-ebc5-2d01-5d34fc18e88f",
   "UUAID": null,
   "coordinates":    [
            {
         "PDC": 10,
         "addressPointType": 0,
         "coordinateType": 1,
         "lat": 43.850174,
         "lon": -79.363277
      },
            {
         "PDC": 50,
         "addressPointType": 1,
         "coordinateType": 1,
         "lat": 43.849769,
         "lon": -79.364969
      }
   ],
   "country": "CANADA",
   "freeFormAddress": "15 ALLSTATE PKY MARKHAM ON L3R5B4",
   "locale": "en-CA",
   "municipality": "MARKHAM",
   "postalCode": "L3R5B4",
   "postalMunicipality": "MARKHAM",
   "provinceState": "ON",
   "residentialFlag": 1,
   "score": 0,
   "streetDirection": null,
   "streetName": "ALLSTATE",
   "streetNumber": 15,
   "streetNumberSuffix": null,
   "streetType": "PKY",
   "unitNumber": null,
   "unitType": null,
   "DA": "35190749",
   "UsedMunicipalityAlias": null
}

Example (Recognize request):

A request for “15 Allstate” will produce the following output:

// Recognize REST Request:
recognize?address=15%20Allstate&limit=20&scoreThreshold=0&format=json
 
//Recognize REST Response:
[{
   "MDUFlag": true,
   "UAID": "5c2d1184-d1b5-ebc5-2d01-5d34fc18e88f",
   "UUAID": null,
   "coordinates":    [
            {
         "PDC": 10,
         "addressPointType": 0,
         "coordinateType": 1,
         "lat": 43.850174,
         "lon": -79.363277
      },
            {
         "PDC": 50,
         "addressPointType": 1,
         "coordinateType": 1,
         "lat": 43.849769,
         "lon": -79.364969
      }
   ],
   "country": "CANADA",
   "freeFormAddress": "15 ALLSTATE PKY MARKHAM ON L3R5B4",
   "locale": "en-CA",
   "municipality": "MARKHAM",
   "postalCode": "L3R5B4",
   "postalMunicipality": "MARKHAM",
   "provinceState": "ON",
   "residentialFlag": 1,
   "score": 0.929,
   "streetDirection": null,
   "streetName": "ALLSTATE",
   "streetNumber": 15,
   "streetNumberSuffix": null,
   "streetType": "PKY",
   "unitNumber": null,
   "unitType": null,
   "DA": "35190749",
   "UsedMunicipalityAlias": null
}]

Example (RecognizeFreeForm request):

A request for “15 Allstate” will produce the following output:

// RecognizeFreeForm REST Request:
recognizefreeform?address=15%20Allstate&maxResults=20&scoreThreshold=0&inferSubAddresses=true&recognizePostalAddresses=true&format=json
 
//RecognizeFreeForm REST Response:
{"ResponseItems": [{
   "InsufficientFlag": true,
   "LocationCandidates": [   {
      "Type": "LocationAddress",
      "UAID": "5c2d1184-d1b5-ebc5-2d01-5d34fc18e88f",
      "RDSID": 5961050,
      "CI": 0.99361,
      "MDUFlag": true,
      "ResidentialFlag": 1,
      "StreetNumber":       {
         "ChangeFlagSpecified": false,
         "Value": 15
      },
      "StreetNumberSuffix":       {
         "ChangeFlagSpecified": false,
         "Value": null
      },
      "StreetPreDirection":       {
         "ChangeFlagSpecified": false,
         "Value": null
      },
      "StreetPreType":       {
         "ChangeFlagSpecified": false,
         "Value": null
      },
      "StreetName":       {
         "ChangeFlagSpecified": false,
         "Value": "ALLSTATE"
      },
      "StreetType":       {
         "ChangeFlag": 2,
         "ChangeFlagSpecified": true,
         "Value": "PKY"
      },
      "StreetDirection":       {
         "ChangeFlagSpecified": false,
         "Value": null
      },
      "PostalCode":       {
         "ChangeFlag": 2,
         "ChangeFlagSpecified": true,
         "IsDerived": false,
         "Value": "L3R5B4"
      },
      "DA": "35190749",
      "IsAsserted": false,
      "IsAssertedSpecified": false,
      "Score": 0.9285714,
      "Coordinates":       [
                  {
            "Lat": 43.850174,
            "Lon": -79.363277,
            "CoordinateType": 1,
            "AddressPointType": 0,
            "AddressPointTypeSpecified": true,
            "LegacyPDC": 105,
            "PMC": 104,
            "PDC": 10
         },
                  {
            "Lat": 43.849769,
            "Lon": -79.364969,
            "CoordinateType": 1,
            "AddressPointType": 1,
            "AddressPointTypeSpecified": true,
            "LegacyPDC": 205,
            "PMC": 505,
            "PDC": 50
         }
      ],
      "AddressLine": "15 ALLSTATE PKY MARKHAM ON L3R5B4",
      "Municipality":       {
         "ChangeFlag": 2,
         "ChangeFlagSpecified": true,
         "Value": "MARKHAM"
      },
      "StateProvince":       {
         "ChangeFlag": 2,
         "ChangeFlagSpecified": true,
         "Value": "ON"
      },
      "Country":       {
         "ChangeFlag": 2,
         "ChangeFlagSpecified": true,
         "Value": "CANADA"
      }
   }],
   "SequenceId": null
}]}