Recognition – REST Batch Service
Table of Contents
REST Batch Operations
There are 3 main Address Recognition batch operation requests available through REST
- RecognizeFreeFormBatch: recognizes one or more single line address strings.
- RecognizeUnparsedBatch: recognizes one or more addresses based on Address Line 1, Address Line 2 and separate fields for Municipality, Province, and Postal Code.
- RecognizeParsedBatch: recognizes one or more addresses based on individual address components.
Parameters
All batch methods require a HTTP POST (PUT) operation. All parameters except the first one are submitted through the query string. The first parameter data (of type Stream) is a set of addresses submitted to the service. This parameter can be in XML, JSON or text form. A user has to specify the content type of the input data when submitting a request.
- for XML, the request content type must be “application/xml”,
- for JSON, the request content type must be “application/json”
- for text, the request content type must be “text/xml”.
For XML and JSON input addresses will be serialized and de-serialized, hence both the client and the service have to use the same data types/classes. For the exact structure of these classes see the section Input Data Classes. For text files, users will have to provide a header row. This row will contain what address elements/columns/fields are present in the file and in what order. Not all columns have to be present and they don’t have to be in the same order. Each column name (address element) has to match one of acceptable names. For the full list of acceptable names see section Submitting Text Input.
The last parameter delimiter is applicable only for plain text submission and specifies the column/field delimiter. Acceptable values are “,” and “|”.
The service will return a collection of zero or more matching address candidates.
All REST Recognition Batch requests have exactly the same list of parameters as shown below:
- data: (type Stream) – The list of addresses submitted in the request. This parameter is submitted within the body of the request and contains one or more addresses formatted in XML, JSON or delimited text.
- 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.
- delimiter: This parameter specifies the delimiting character for delimited text data only. Supported characters are “,” and “|”.
Input Data Classes
The following data structures are required when submitting addresses in batch to be processed by the REST service:
FreeFormAddress:
Class Definition:
vclass FreeFormAddress
{
string Address;
string SequenceId;
}
XML Schema:
<?xml version="1.0" encoding="utf-8"?>
<xs:schema elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="FreeFormAddress" nillable="true" type="FreeFormAddress" />
<xs:complexType name="FreeFormAddress">
<xs:sequence>
<xs:element minOccurs="0" maxOccurs="1" name="Address" type="xs:string" />
<xs:element minOccurs="0" maxOccurs="1" name="SequenceId" type="xs:string" />
</xs:sequence>
</xs:complexType>
</xs:schema>
UnparsedAddress:
Class Definition:
class UnparsedAddress
{
string AddressLine1;
string AddressLine2;
string Municipality;
string ProvinceState;
string PostalCode;
string Country;
string SequenceId;
}
XML Schema:
<?xml version="1.0" encoding="utf-8"?>
<xs:schema elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="UnparsedAddress" nillable="true" type="UnparsedAddress" />
<xs:complexType name="UnparsedAddress">
<xs:sequence>
<xs:element minOccurs="0" maxOccurs="1" name="AddressLine1" type="xs:string" />
<xs:element minOccurs="0" maxOccurs="1" name="AddressLine2" type="xs:string" />
<xs:element minOccurs="0" maxOccurs="1" name="Municipality" type="xs:string" />
<xs:element minOccurs="0" maxOccurs="1" name="ProvinceState" type="xs:string" />
<xs:element minOccurs="0" maxOccurs="1" name="PostalCode" type="xs:string" />
<xs:element minOccurs="0" maxOccurs="1" name="Country" type="xs:string" />
<xs:element minOccurs="0" maxOccurs="1" name="SequenceId" type="xs:string" />
</xs:sequence>
</xs:complexType>
</xs:schema>
ParsedAddress:
Class Definition:
class ParsedAddress
{
uint StreetNumber;
string StreetNumberSuffix;
string StreetPreDirection;
string StreetPreType;
string StreetName;
string StreetType;
string StreetDirection;
string SubAddressType;
string SubAddressNumber;
string Municipality;
string ProvinceState;
string PostalCode;
string Country;
string SequenceId;
}
XML Schema:
<?xml version="1.0" encoding="utf-8"?>
<xs:schema elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="ParsedAddress" nillable="true" type="ParsedAddress" />
<xs:complexType name="ParsedAddress">
<xs:sequence>
<xs:element minOccurs="1" maxOccurs="1" name="StreetNumber" type="xs:unsignedInt" />
<xs:element minOccurs="0" maxOccurs="1" name="StreetNumberSuffix" type="xs:string" />
<xs:element minOccurs="0" maxOccurs="1" name="StreetPreDirection" type="xs:string" />
<xs:element minOccurs="0" maxOccurs="1" name="StreetPreType" type="xs:string" />
<xs:element minOccurs="0" maxOccurs="1" name="StreetName" type="xs:string" />
<xs:element minOccurs="0" maxOccurs="1" name="StreetType" type="xs:string" />
<xs:element minOccurs="0" maxOccurs="1" name="StreetDirection" type="xs:string" />
<xs:element minOccurs="0" maxOccurs="1" name="SubAddressType" type="xs:string" />
<xs:element minOccurs="0" maxOccurs="1" name="SubAddressNumber" type="xs:string" />
<xs:element minOccurs="0" maxOccurs="1" name="Municipality" type="xs:string" />
<xs:element minOccurs="0" maxOccurs="1" name="ProvinceState" type="xs:string" />
<xs:element minOccurs="0" maxOccurs="1" name="PostalCode" type="xs:string" />
<xs:element minOccurs="0" maxOccurs="1" name="Country" type="xs:string" />
<xs:element minOccurs="0" maxOccurs="1" name="SequenceId" type="xs:string" />
</xs:sequence>
</xs:complexType>
</xs:schema>
Submitting Text Input
When submitting addresses as plain text, one row contains one address. It is not required to specify the number or the order of the columns. The first row is required to be a header row containing the column names. The header row can be delimited by either a comma (“,”) or pipe (vertical bar “|”). All column names have to match one of the acceptable names listed below. The following table contains the list of acceptable column names including their supported aliases.
FreeFormAddress Column Names:
| Column Name |
Supported Aliases |
Description |
| RowID |
Row ID |
Unique Row Identifier |
| Address |
Free Form Address |
Single Line Address fully concatenated |
UnparsedAddress Column Names:
| Column Name |
Supported Aliases |
Description |
| RowID |
Row ID |
Unique Row Identifier |
| AddressLine1 |
Address Line 1, Address 1 |
Address Line 1 – typically street address like “15 Allstate Parkway” |
| AddressLine2 |
Address Line 2, Address 2 |
Address Line 2 – typically unit address like “Unit 400” |
| Municipality |
Muni, City |
Municipality or City Name |
| ProvinceState |
Province, Prov/State, Prov |
Province Name |
| PostalCode |
Postal Code, P Code, PCode, PC |
Postal Code |
| Country |
|
Country |
ParsedAddress Column Names:
| Column Name |
Supported Aliases |
Description |
| RowID |
Row ID |
Unique Row Identifier |
| StreetNumber |
Street Number, St Number, Street No, St No |
Street Number |
| StreetNumberSuffix |
Street Number Suffix, St Number Suffix, Street No Suffix, St No Suffix |
Street Number Suffix |
| StreetPreDirection |
Street Pre Direction, St Pre Direction, St Pre Dir, Pre Direction, Pre Dir |
Street Pre Direction |
| StreetPreType |
Street Pre Type, St Pre Type, Pre Type |
Street Pre Type |
| StreetName |
Street Name, St Name |
Street Name |
| StreetType |
Street Type, St Type |
Street Type |
| StreetDirection |
Street Direction, St Direction, St Dir |
Street Direction |
| SubAddressType |
Sub Address Type, Unit Type |
Unit Type |
| SubAddressNumber |
Sub Address Number, Sub Address No, Unit Number, Unit No |
Unit Number |
| Municipality |
Muni, City |
Municipality or City Name |
| ProvinceState |
Province, Prov/State, Prov |
Province Name |
| PostalCode |
Postal Code, P Code, PCode, PC |
Postal Code |
| Country |
|
Country |
Examples
RecognizeFreeFormBatch Request
XML
POST https://lhrecognition.dmtispatial.com/services/Rest/RecognizeFreeFormBatch?maxResults=3&scoreThreshold=0.2&inferSubAddresses=true&recognizePostalAddresses=true&format=json HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: application/xml
Authorization: WRAP access_token="********************************"
Content-Length: 595
Host: lhrecognition.dmtispatial.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
<?xml version="1.0" encoding="utf-16"?>
<ArrayOfFreeFormAddress xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<FreeFormAddress>
<Address>15 allstate parkway suite 400 markham on</Address>
<SequenceId>S001</SequenceId>
</FreeFormAddress>
<FreeFormAddress>
<Address>30 Leek crescent unit 202 Richmond Hill ON</Address>
<SequenceId>S002</SequenceId>
</FreeFormAddress>
<FreeFormAddress>
<Address>260 King St W, Toronto, ON</Address>
<SequenceId>S003</SequenceId>
</FreeFormAddress>
</ArrayOfFreeFormAddress>
JSON
POST https://lhrecognition.dmtispatial.com/services/Rest/RecognizeFreeFormBatch?maxResults=3&inferSubAddresses=true HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: application/json
Authorization: WRAP access_token="********************************"
Content-Length: 260
Host: lhrecognition.dmtispatial.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
[{
"Address":"15 allstate parkway suite 400 markham on",
"SequenceId":"S001"
},
{
"Address":"30 Leek crescent unit 202 Richmond Hill ON",
"SequenceId":"S002"
},
{
"Address":"260 King St W, Toronto, ON",
"SequenceId":"S003"
}]
Text
POST https://lhrecognition.dmtispatial.com/services/Rest/RecognizeFreeFormBatch?inferSubAddresses=true&format=json&delimiter=%22%7C%22 HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: text/xml
Authorization: WRAP access_token="********************************"
Content-Length: 131
Host: lhrecognition.dmtispatial.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
Row ID,Address
1|15 allstate parkway suite 400 markham on
2|30 Leek crescent unit 202 Richmond Hill ON
3|260 King St W, Toronto, ON
RecognizeUnparsedBatch Request
XML
POST https://lhrecognition.dmtispatial.com/services/Rest/RecognizeUnparsedBatch?maxResults=3&inferSubAddresses=true HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: application/xml
Authorization: WRAP access_token="********************************"
Content-Length: 987
Host: lhrecognition.dmtispatial.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
<?xml version="1.0" encoding="utf-16"?>
<ArrayOfUnparsedAddress xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<UnparsedAddress>
<AddressLine1>15 allstate parkway</AddressLine1>
<AddressLine2>Suite 400</AddressLine2>
<Municipality>Markham</Municipality>
<ProvinceState>ON</ProvinceState>
<PostalCode></PostalCode>
<Country>Canada</Country>
<SequenceId>S001</SequenceId>
</UnparsedAddress>
<UnparsedAddress>
<AddressLine1>30 Leek Crescent</AddressLine1>
<AddressLine2>Unit 202</AddressLine2>
<Municipality>Richmond Hill</Municipality>
<ProvinceState>ON</ProvinceState>
<SequenceId>S002</SequenceId>
</UnparsedAddress>
<UnparsedAddress>
<AddressLine1>260 King St W</AddressLine1>
<AddressLine2></AddressLine2>
<Municipality>Toronto</Municipality>
<ProvinceState>ON</ProvinceState>
<SequenceId>S003</SequenceId>
</UnparsedAddress>
</ArrayOfUnparsedAddress>
JSON
POST https://lhrecognition.dmtispatial.com/services/Rest/RecognizeUnparsedBatch?maxResults=10&scoreThreshold=0&inferSubAddresses=true&recognizePostalAddresses=true HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: application/json
Authorization: WRAP access_token="********************************"
Content-Length: 490
Host: lhrecognition.dmtispatial.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
[{
"AddressLine1":"15 allstate parkway",
"AddressLine2":"suite 400",
"Municipality":"Markham",
"ProvinceState":"ON",
"PostalCode":"L3R5B4",
"Country":"Canada",
"SequenceId":"1"
},
{
"AddressLine1":"30 Leek Cres",
"AddressLine2":"Unit 202",
"Municipality":"Richmond Hill",
"ProvinceState":"ON",
"SequenceId":"2"
},
{
"AddressLine1":"260 King St W",
"Municipality":"Toronto",
"ProvinceState":"ON",
"SequenceId":"3"
}]
Text
POST https://lhrecognition.dmtispatial.com/services/Rest/RecognizeUnparsedBatch?maxResults=3&inferSubAddresses=true&recognizePostalAddresses=true&format=json HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: text/xml
Authorization: WRAP access_token="********************************"
Content-Length: 189
Host: lhrecognition.dmtispatial.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
RowId, Address 1, Address 2, city, province, postal code
One, 15 allstate pky,suite 400, markham,on,l3r 5b4
Two, 30 Leek Cres,Unit 202, Richmond Hill, ON,
Three, 260 King St W,,Toronto,On,
RecognizeParsedBatch Request
XML
POST https://lhrecognition.dmtispatial.com/services/Rest/RecognizeParsedBatch?inferSubAddresses=true HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: application/xml
Authorization: WRAP access_token="********************************"
Content-Length: 1295
Host: lhrecognition.dmtispatial.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
<?xml version="1.0" encoding="utf-16"?>
<ArrayOfParsedAddress xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ParsedAddress>
<StreetNumber>15</StreetNumber>
<StreetName>allstate</StreetName>
<StreetType>pky</StreetType>
<SubAddressType>Suite</SubAddressType>
<SubAddressNumber>400</SubAddressNumber>
<Municipality>Markham</Municipality>
<ProvinceState>ON</ProvinceState>
<PostalCode>L3R5B4</PostalCode>
<Country>Canada</Country>
<SequenceId>101</SequenceId>
</ParsedAddress>
<ParsedAddress>
<StreetNumber>30</StreetNumber>
<StreetName>Leek</StreetName>
<StreetType>Crescent</StreetType>
<SubAddressType>Unit</SubAddressType>
<SubAddressNumber>202</SubAddressNumber>
<Municipality>Richmond Hill</Municipality>
<ProvinceState>ON</ProvinceState>
<SequenceId>102</SequenceId>
</ParsedAddress>
<ParsedAddress>
<StreetNumber>260</StreetNumber>
<StreetName>King</StreetName>
<StreetType>St</StreetType>
<StreetDirection>W</StreetDirection>
<Municipality>Toronto</Municipality>
<ProvinceState>ON</ProvinceState>
<PostalCode></PostalCode>
<Country></Country>
<SequenceId>103</SequenceId>
</ParsedAddress>
</ArrayOfParsedAddress>
JSON
POST https://lhrecognition.dmtispatial.com/services/Rest/RecognizeParsedBatch?inferSubAddresses=true HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: application/json
Authorization: WRAP access_token="********************************"
Content-Length: 627
Host: lhrecognition.dmtispatial.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
[
{
"StreetNumber":15,
"StreetName":"allstate",
"StreetType":"parkway",
"SubAddressType":"Suite",
"SubAddressNumber":"400",
"Municipality":"Markham",
"ProvinceState":"ON",
"PostalCode":"L3R5B4",
"Country":"Canada",
"SequenceId":"101"
},
{
"StreetNumber":30,
"StreetName":"Leek",
"StreetType":"Crescent",
"Municipality":"Richmond Hill",
"SubAddressType":"Unit",
"SubAddressNumber":"202",
"ProvinceState":"ON",
"SequenceId":"102"
},
{
"StreetNumber":260,
"StreetName":"King",
"StreetType":"St",
"StreetDirection":"W",
"Municipality":"Toronto",
"ProvinceState":"ON",
"SequenceId":"103"
}
]
Text
POST https://lhrecognition.dmtispatial.com/services/Rest/RecognizeParsedBatch?inferSubAddresses=true&format=json HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: text/xml
Authorization: WRAP access_token="********************************"
Content-Length: 227
Host: lhrecognition.dmtispatial.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
Row id, street number, st name, st type, st direction,unit type,unit number, city, prov, pc
101,15, allstate, pky,,Suite,400,markham, on,
102, 30, Leek, Cres,,Unit,202, Richmod Hill, on, l4b 4n4
103, 260,King,St,W,,,Toronto,ON,
SOAP Operations
There are 4 main address recognition operations available through SOAP/XML
Options
Each Recognize SOAP/XML operation accepts Options that affect the behavior of the recognition process. The most commonly customized are:
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:
The following tables summarize the descriptions and values where applicable for each of the returned data fields from the service.
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:
*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.