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:

class 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,