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