PageCategory: Location Hub

Reverse Geocode

Reverse Geocode

The Location Hub® Reverse Geocode Service processes geographic coordinates and quickly returns the closest validated address and attributes.

What Does it Do?

The service allows for users to identify address points through a unique identifier by passing a latitude and longitude coordinate to the service. It converts input geographic coordinates (latitude and longitude) to the closest validated address and associated attributes. This allows you to translate geographic coordinates captured by mobile or GPS devices to real street addresses. Field technicians can use the service to find information on nearby addresses.

The Reverse Geocode service supports SOAP and REST based requests and is able to return information on both address points and road segments. Please note that all coordinates must be passed to the service in WGS84.

Accessing the Service

To access the Location Hub Reverse Geocode service you must first be authorized for use with Location Hub Web Services in order to have a valid user name and password. Please contact info@dmtispatial.com for more information on how to register for Location Hub Reverse Geocode Web Service.

Once you have a valid user name and password, please refer to the Authentication section for information on how to access the service.

SOAP Service

Soap Operations
There are 4 Reverse Geocode operation requests available through SOAP/XML

  • FindNearestAddressByPoint: Returns the closest point feature (Address or Enhanced Point of Interest (EPOI)) to the given location
  • FindAddressByPoint: Returns all the closest point features (Address or Enhanced Point of Interest (EPOI)) to the given location, limited by the maximum number specified, and sorted by the distance. The first feature in the response list is the closest point feature.
  • FindNearestRoadByPoint: Returns the closest road segment to the given location
  • FindRoadByPoint: Returns all the closest road segments to the given location, limited by the maximum number specified, and sorted by the distance. The first feature in the response list is the closest road segment.

Parameters

The following parameters are required by all Reverse Geocode Operations:

  • Lat (double): The WGS84 latitude of the location specified
  • Lon (double): The WGS84 longitude of the location specified

The following parameter is required by the FindNearestAddressByPoint and the FindAddressByPoint operations only:

  • PointType (RGPointType): The type of point features (Address or EPOI) to be searched

The following parameter is optional in the FindAddressByPoint and the FindRoadByPoint operations only:

  • maxReturns (int): The maximum number of point features or road segments to return. The default value is 1 if not provided.

Examples:

<!-- The SOAP/XML Request -->
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v1="http://www.dmtispatial.com/reversegeocode/v1.0/">
   <soapenv:Header/>
   <soapenv:Body>
      <v1:FindNearestAddressByPointRequest>
         <!--type: RGPointType - enumeration: [Address,EPOI]-->
         <v1:PointType>Address</v1:PointType>
         <!--type: double-->
         <v1:Lat>43.850839</v1:Lat>
         <!--type: double-->
         <v1:Lon>-79.363686</v1:Lon>
      </v1:FindNearestAddressByPointRequest>
   </soapenv:Body>
</soapenv:Envelope>
 
<!-- The SOAP/XML Response -->
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
   <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
      <FindNearestAddressByPointResponse xmlns="http://www.dmtispatial.com/reversegeocode/v1.0/">
         <RGPoint>
            <ID>5c2d1184-d1b5-ebc5-2d01-5d34fc18e88f</ID>
            <Name>15 ALLSTATE PKY MARKHAM ON L3R5B4</Name>
            <Lat>43.850174</Lat>
            <Lon>-79.363277</Lon>
         </RGPoint>
      </FindNearestAddressByPointResponse>
   </s:Body>
</s:Envelope>
 
<!-- The SOAP/XML Request -->
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v1="http://www.dmtispatial.com/reversegeocode/v1.0/">
   <soapenv:Header/>
   <soapenv:Body>
      <v1:FindAddressByPointRequest>
         <!--type: RGPointType - enumeration: [Address,EPOI]-->
         <v1:PointType>Address</v1:PointType>
         <!--type: double-->
         <v1:Lat>43.850839</v1:Lat>
         <!--type: double-->
         <v1:Lon>-79.363686</v1:Lon>
         <!--type: int-->
         <v1:maxReturns>3</v1:maxReturns>
      </v1:FindAddressByPointRequest>
   </soapenv:Body>
</soapenv:Envelope>
 
<!-- The SOAP/XML Response -->
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
   <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
      <FindAddressByPointResponse xmlns="http://www.dmtispatial.com/reversegeocode/v1.0/">
         <RGPoints>
            <ID>5c2d1184-d1b5-ebc5-2d01-5d34fc18e88f</ID>
            <Name>15 ALLSTATE PKY MARKHAM ON L3R5B4</Name>
            <Lat>43.850174</Lat>
            <Lon>-79.363277</Lon>
         </RGPoints>
         <RGPoints>
            <ID>acc011b0-e092-51d1-212b-0a25098f2ebb</ID>
            <Name>11 ALLSTATE PKY MARKHAM ON L3R9T8</Name>
            <Lat>43.8504168</Lat>
            <Lon>-79.3645531</Lon>
         </RGPoints>
         <RGPoints>
            <ID>512e1108-3d54-fd0d-5c01-828ea7475d03</ID>
            <Name>19 ALLSTATE PKY MARKHAM ON L3R5A4</Name>
            <Lat>43.850833</Lat>
            <Lon>-79.3626248</Lon>
         </RGPoints>
      </FindAddressByPointResponse>
   </s:Body>
</s:Envelope>
 
<!-- The SOAP/XML Request -->
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v1="http://www.dmtispatial.com/reversegeocode/v1.0/">
   <soapenv:Header/>
   <soapenv:Body>
      <v1:FindNearestRoadByPointRequest>
         <!--type: double-->
         <v1:Lat>43.850839</v1:Lat>
         <!--type: double-->
         <v1:Lon>-79.363686</v1:Lon>
      </v1:FindNearestRoadByPointRequest>
   </soapenv:Body>
</soapenv:Envelope>
 
<!-- The SOAP/XML Response -->
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
   <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
      <FindNearestRoadByPointResponse xmlns="http://www.dmtispatial.com/reversegeocode/v1.0/">
         <RGRoad>
            <RDSID>9443789</RDSID>
            <Name>FRONTENAC</Name>
            <LineString>
               <double>-79.361379</double>
               <double>43.849256</double>
               <double>-79.361403</double>
               <double>43.84935</double>
                       ...
                       ...
                       ...
               <double>-79.362103244102116</double>
               <double>43.851377410485178</double>
            </LineString>
         </RGRoad>
      </FindNearestRoadByPointResponse>
   </s:Body>
</s:Envelope>
 
<!-- The SOAP/XML Request -->
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v1="http://www.dmtispatial.com/reversegeocode/v1.0/">
   <soapenv:Header/>
   <soapenv:Body>
      <v1:FindRoadByPointRequest>
         <!--type: double-->
         <v1:Lat>43.850839</v1:Lat>
         <!--type: double-->
         <v1:Lon>-79.363686</v1:Lon>
         <!--type: int-->
         <v1:maxReturns>3</v1:maxReturns>
      </v1:FindRoadByPointRequest>
   </soapenv:Body>
</soapenv:Envelope>
 
<!-- The SOAP/XML Response -->
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
   <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
      <FindRoadByPointResponse xmlns="http://www.dmtispatial.com/reversegeocode/v1.0/">
         <RGRoads>
            <RDSID>9443789</RDSID>
            <Name>FRONTENAC</Name>
            <LineString>
               <double>-79.361379</double>
               <double>43.849256</double>
                       ...
                       ...
                       ...
               <double>-79.362103244102116</double>
               <double>43.851377410485178</double>
            </LineString>
         </RGRoads>
         <RGRoads>
            <RDSID>9443790</RDSID>
            <Name>FRONTENAC</Name>
            <LineString>
               <double>-79.362103244102116</double>
               <double>43.851377410485178</double>
               <double>-79.362128668665434</double>
               <double>43.85146936975805</double>
            </LineString>
         </RGRoads>
         <RGRoads>
            <RDSID>9443767</RDSID>
            <Name>FRONTENAC</Name>
            <LineString>
               <double>-79.362128668665434</double>
               <double>43.85146936975805</double>
               <double>-79.362443</double>
               <double>43.852616</double>
            </LineString>
         </RGRoads>
      </FindRoadByPointResponse>
   </s:Body>
</s:Envelope>

REST Service

REST Operations

There are 4 Reverse Geocode operation requests available through REST

  • FindNearestAddressByPoint: Returns the closest point feature (Address or Enhanced Point of Interest (EPOI)) to the given location
  • FindAddressByPoint: Returns all the closest point features (Address or Enhanced Point of Interest (EPOI)) to the given location, limited by the maximum number specified, and sorted by the distance. The first feature in the response list is the closest point feature.
  • FindNearestRoadByPoint: Returns the closest road segment to the given location
  • FindRoadByPoint: Returns all the closest road segments to the given location, limited by the maximum number specified, and sorted by the distance. The first feature in the response list is the closest road segment.

Parameters

The following parameters are required by all Reverse Geocode Opeartions:

  • lat: The WGS84 latitude of the location specified
  • lon: The WGS84 longitude of the location specified

The following parameter is required by the FindNearestAddressByPoint and the FindAddressByPoint operations only:

  • ptype: The type of point features (Address or EPOI) to be searched

The following parameter is optional in the FindAddressByPoint and the FindRoadByPoint operations only:

  • limit: The maximum number of point features or road segments to return. The default value is 1 if not provided.

Examples:

<!-- The REST url Request -->
http://lhreversegeocode.dmtispatial.com/ReverseGeocodeService.svc/rest/FindNearestAddressByPoint?ptype=Address&lat=43.850839&lon=-79.363686
 
<!-- The JSON Response -->
{
   "ID": "5c2d1184-d1b5-ebc5-2d01-5d34fc18e88f",
   "Lat": 43.850174,
   "Lon": -79.363277,
   "Name": "15 ALLSTATE PKY MARKHAM ON L3R5B4",
   "UAID": "5c2d1184-d1b5-ebc5-2d01-5d34fc18e88f"
}
 
<!-- The REST url Request -->
http://lhreversegeocode.dmtispatial.com/ReverseGeocodeService.svc/rest/FindAddressByPoint?ptype=Address&lat=43.850839&lon=-79.363686&limit=3
 
<!-- The JSON Response -->
[
      {
      "ID": "5c2d1184-d1b5-ebc5-2d01-5d34fc18e88f",
      "Lat": 43.850174,
      "Lon": -79.363277,
      "Name": "15 ALLSTATE PKY MARKHAM ON L3R5B4",
      "UAID": "5c2d1184-d1b5-ebc5-2d01-5d34fc18e88f"
   },
      {
      "ID": "acc011b0-e092-51d1-212b-0a25098f2ebb",
      "Lat": 43.8504168,
      "Lon": -79.3645531,
      "Name": "11 ALLSTATE PKY MARKHAM ON L3R9T8",
      "UAID": "acc011b0-e092-51d1-212b-0a25098f2ebb"
   },
      {
      "ID": "512e1108-3d54-fd0d-5c01-828ea7475d03",
      "Lat": 43.850833,
      "Lon": -79.3626248,
      "Name": "19 ALLSTATE PKY MARKHAM ON L3R5A4",
      "UAID": "512e1108-3d54-fd0d-5c01-828ea7475d03"
   }
]
 
<!-- The REST url Request -->
http://lhreversegeocode.dmtispatial.com/ReverseGeocodeService.svc/rest/FindNearestRoadByPoint?lat=43.850839&lon=-79.363686
 
<!-- The JSON Response -->
{
   "LineString":    [
      -79.361379,
      43.849256,
         ...
         ...
         ...
      -79.36210324410212,
      43.85137741048518
   ],
   "Name": "FRONTENAC",
   "RDSID": 9443789
}
 
<!-- The REST url Request -->
http://lhreversegeocode.dmtispatial.com/ReverseGeocodeService.svc/rest/FindRoadByPoint?lat=43.850839&lon=-79.363686&limit=3
 
<!-- The JSON Response -->
[
      {
      "LineString":       [
         -79.361379,
         43.849256,
            ...
            ...
            ...
         -79.36210324410212,
         43.85137741048518
      ],
      "Name": "FRONTENAC",
      "RDSID": 9443789
   },
      {
      "LineString":       [
         -79.36210324410212,
         43.85137741048518,
         -79.36212866866543,
         43.85146936975805
      ],
      "Name": "FRONTENAC",
      "RDSID": 9443790
   },
      {
      "LineString":       [
         -79.36212866866543,
         43.85146936975805,
         -79.362443,
         43.852616
      ],
      "Name": "FRONTENAC",
      "RDSID": 9443767
   }
]

Proximity Service

Proximity Service

The Location Hub Proximity Service (also known as the Drive Time and Drive Distance Service) provides proximity functionality that allows you to understand the distance between an address and a specified feature such as other addresses, points of interest, major highways, or other locations. The proximity of an address to various points can be used to determine the risk associated with that location. For example, when insuring a property that is in close proximity to a fire station, less risk may be involved. Whereas, the close proximity of a property to a body of water may indicate a high risk to the property for flood.

What Does it Do?

Using an address or a set of coordinates as a starting point, the Proximity Service can calculate and return the addresses (and associated attribution information) within a specified drive time or drive distance. In addition to the addresses returned, the service can also return the polygon representing the area within a specified drive time or distance allowing you to visualize the boundary on a map. The service has the ability to return the results abiding by the rules of the road, such as one way streets, turn restrictions, and highway on ramps. Options are available to remove rules of the road and calculate travel in any direction along the road network. This feature is particularly useful for proximity to fire stations for insurance purposes, as fire trucks can travel the wrong way on a one-way street to reach a fire. The service can also calculate straight line distance between locations.

The Proximity Service also has the ability to return the route between locations. The service provides options to calculate the route based on the shortest time or the shortest distance and the option to return information on the associated road segments. This feature is particularly useful for efficiently routing trucks for service calls to increase serviceability.

Accessing the Service

To access the Location Hub Proximity Service you must first be authorized for use with Location Hub Web Services in order to have a valid user name and password. Please contact info@dmtispatial.com for more information on how to register for the Location Hub Proximity Service.

Once you have a valid user name and password, please refer to the Authentication section for information on how to access the service.

SOAP Service

SOAP Operations
The following Proximity Service operations are available through SOAP/XML:

  • GetCapabilities: Returns the Features (Layers) available in the DriveFeatures request
  • DriveFeatures: Returns a list of features that are within a specified distance or time from the specified coordinate using the specified Drive Mode
  • DrivePolygon: This operation calculates and returns the polygon area as Lat/Long points that represents the area that can be reached within a specified distance or time from the specified coordinate using the specified Drive Mode
  • DriveTimeDistance: This operation calculates the route from a specified start location to a specified end location using the specified Drive Mode
  • FindFirstFeature: Returns the first feature that is within a specified distance or time from the specified coordinate using the specified Drive Mode
  • AddLayer: This operation creates a new dynamic layer to the service instance. A dynamic layer in this service is defined by users during the service runtime. The layer and the features inside can be managed by the user
  • DeleteLayer: This operation removes an existing dynamic layer from the service instance. All features defined in this dynamic layer will be deleted
  • AddFeatures: This operation adds features to an existing dynamic layer in the service instance
  • DeleteFeatures: This operation removes a list of features identified by their IDs from an existing dynamic layer in the service instance

REST Service

REST Operations
The following Proximity Service request operations are available through REST:

  • GetCapabilities: Returns the Features (Layers) available in the DriveFeatures request
  • DriveFeatures: Returns a list of features that are within a specified distance or time from the specified coordinate using the specified Drive Mode
  • DrivePolygon: This operation calculates and returns the polygon area as Lat/Long points that represents the area that can be reached within a specified distance or time from the specified coordinate using the specified Drive Mode
  • DriveTimeDistance: This operation calculates the route from a specified start location to a specified end location using the specified Drive Mode
  • FindFirstFeature: Returns the first feature that is within a specified distance or time from the specified coordinate using the specified Drive Mode
  • DriveFeaturesGML: Returns a list of features expressed as Geography Markup Language (GML) points that are within a specified distance or time from the specified coordinate using the specified Drive Mode
  • DrivePolygonGML: This operation calculates and returns the area expressed as a Geography Markup Language (GML) polygon feature that represents the area that can be reached within a specified distance or time from the specified coordinate using the specified Drive Mode
  • DriveFeaturesFromAddress: Returns a list of features that are within a specified distance or time from the provided UAID using the specified Drive Mode
  • DriveFeaturesFromAddressGML: Returns a list of features expressed as Geography Markup Language (GML) points that are within a specified distance or time from the provided UAID using the specified Drive Mode
  • DrivePolygonFromAddress: This operation calculates and returns the polygon area as Lat/Long points that represents the area that can be reached within a specified distance or time from the specified address using the specified Drive Mode
  • DrivePolygonFromAddressGML: This operation calculates and returns the area expressed as a Geography Markup Language (GML) polygon feature that represents the area that can be reached within a specified distance or time from the specified address using the specified Drive Mode
  • DriveTimeDistanceBetweenAddresses: This operation calculates the route from a specified start location address (UAID) to a specified end location address (UAID) using the specified Drive Mode
  • FindFirstFeatureFromAddress: Returns the first feature that is within a specified distance or time from the specified address UAID using the specified Drive Mode

Request Operation Parameters

Request Protocols SOAP Parameters REST Parameters
GetCapabilities SOAP and REST N/A N/A
DriveFeatures SOAP and REST Feature (string): The name of the feature layer to be searched

Mode (DriveMode): The travel mode of this operation (DriveTime, DriveDistance, RoadDistance, SpatialDistance)

StartLocation (RouteLocation):

The location (Lat/Long coordinate object) of the Starting Point or End Point of the search.

DriveValue (double):

The travel time or distance of the operation

ValueMode (DriveValueMode):

The travel direction of this operation (FromStartLocation, ToStartLocation, FromStartLocationRoundTrip)

 layer: The name of the feature layer to be searched

mode: The travel mode of this operation (DriveTime, DriveDistance, RoadDistance, SpatialDistance)

lat: The Latitude of the Starting Point or End Point of the search

lon: The Longitude of the Starting Point or End Point of the search

value: The travel time or distance of the operation

valuemode: The travel direction of this operation (FromStartLocation, ToStartLocation, FromStartLocationRoundTrip)
DrivePolygon SOAP and REST Mode (DriveMode): The travel mode of this operation (DriveTime, DriveDistance, RoadDistance, SpatialDistance)

StartLocation (RouteLocation): The location (Lat/Long coordinate object) of the Starting Point of the search.

DriveValue (double): The travel time or distance of the operation

 mode: The travel mode of this operation (DriveTime, DriveDistance, RoadDistance, SpatialDistance)

lat: The Latitude of the Starting Point of the search

lon: The Longitude of the Starting Point of the search

value: The travel time or distance of the operation
DriveTimeDistance SOAP and REST Mode (DriveMode): The travel mode of this operation (DriveTime, DriveDistance, RoadDistance, SpatialDistance)

StartLocation (RouteLocation): The location (Lat/Long coordinate object) of the Starting Point of the route

EndLocation (RouteLocation): The location (Lat/Long coordinate object) of the End Point of the route

ReturnRoadSegmentGeometry (boolean): The option to specify whether or not to return the road segment geometry of the calculated route (true or false)

 mode: The travel mode of this operation (DriveTime, DriveDistance, RoadDistance, SpatialDistance)

startlat: The Latitude of the Starting Point of the route

startlon: The Longitude of the Starting Point of the route

endlat: The Latitude of the End Point of the route

endlon: The Longitude of the End Point of the route

geom: The option to specify whether or not to return the road segment geometry of the calculated route (true or false)
FindFirstFeature SOAP and REST Feature (string): The name of the feature layer to be searched

Mode (DriveMode): The travel mode of this operation (DriveTime, DriveDistance, RoadDistance, SpatialDistance)

StartLocation (RouteLocation): The location (Lat/Long coordinate object) of the Starting Point or End Point of the search.

MaxSearchValue (double): The maximum travel time or distance of the operation

ValueMode (DriveValueMode): The travel direction of this operation (FromStartLocation, ToStartLocation, FromStartLocationRoundTrip)

 layer: The name of the feature layer to be searched

mode: The travel mode of this operation (DriveTime, DriveDistance, RoadDistance, SpatialDistance)

lat: The Latitude of the Starting Point or End Point of the search

lon: The Longitude of the Starting Point or End Point of the search

max: The maximum travel time or distance of the search before the first feature is found

valuemode: The travel direction of this operation (FromStartLocation, ToStartLocation, FromStartLocationRoundTrip)
DriveFeaturesGML REST N/A layer: The name of the feature layer to be searched

mode: The travel mode of this operation (DriveTime, DriveDistance, RoadDistance, SpatialDistance)

lat: The Latitude of the Starting Point or End Point of the search

lon: The Longitude of the Starting Point or End Point of the search

value: The travel time or distance of the operation

valuemode: The travel direction of this operation (FromStartLocation, ToStartLocation, FromStartLocationRoundTrip)
DrivePolygonGML REST N/A mode: The travel mode of this operation (DriveTime, DriveDistance, RoadDistance, SpatialDistance)

lat: The Latitude of the Starting Point of the search

lon: The Longitude of the Starting Point of the search

value: The travel time or distance of the operation
DriveFeaturesFromAddress REST N/A layer: The name of the feature layer to be searched

mode: The travel mode of this operation (DriveTime, DriveDistance, RoadDistance, SpatialDistance)

address: The UAID of the Starting Point or End Point address of the search

value: The travel time or distance of the operation

valuemode: The travel direction of this operation (FromStartLocation, ToStartLocation, FromStartLocationRoundTrip)
DriveFeaturesFromAddressGML REST N/A layer: The name of the feature layer to be searched

mode: The travel mode of this operation (DriveTime, DriveDistance, RoadDistance, SpatialDistance)

address: The UAID of the Starting Point or End Point address of the search

value: The travel time or distance of the operation

valuemode: The travel direction of this operation (FromStartLocation, ToStartLocation, FromStartLocationRoundTrip)
DrivePolygonFromAddress
 REST N/A mode: The travel mode of this operation (DriveTime, DriveDistance, RoadDistance, SpatialDistance)

address: The UAID of the Starting Point or End Point address of the search

value: The travel time or distance of the operation
DrivePolygonFromAddressGML
 REST N/A mode: The travel mode of this operation (DriveTime, DriveDistance, RoadDistance, SpatialDistance)

address: The UAID of the Starting Point or End Point address of the search

value: The travel time or distance of the operation
DriveTimeDistanceBetweenAddresses
 REST N/A mode: The travel mode of this operation (DriveTime, DriveDistance, RoadDistance, SpatialDistance)

startuaid: The UAID of the Starting Point address of the route

enduaid: The UAID of the End Point address of the route

geom: The option to specify whether or not to return the road segment geometry of the calculated route (true or false)
FindFirstFeatureFromAddress
 REST N/A layer: The name of the feature layer to be searched

mode: The travel mode of this operation (DriveTime, DriveDistance, RoadDistance, SpatialDistance)

address: The UAID of the Starting Point or End Point of the search

max: The maximum travel time or distance of the search before the first feature is found

valuemode: The travel direction of this operation (FromStartLocation, ToStartLocation, FromStartLocationRoundTrip)
AddLayer
 SOAP LayerID (string): The id (or Name) of the dynamic layer to be added to the service. Once it is defined, the user can use this id in the DriveFeatures related operations to specify which feature layer to search

GeometryType (FeatureGeometryType): The geometry type of this dynamic layer. All features in a layer must have the same geometry type (Point, LineString, or Polygon).

 N/A
DeleteLayer
 SOAP LayerID (string): The id (or Name) of the dynamic layer to be deleted from the service.

LayerID (string): The id (or Name) of the dynamic layer to which the new feature will be added.

 N/A
AddFeatures
 SOAP Features (LayerFeature): The list of features to be added to the dynamic layer. The LayerFeature object can be either PointLayerFeature, LineStringLayerFeature, or PolygonLayerFeature. N/A
DeleteFeatures
 SOAP LayerID (string): The id (or Name) of the dynamic layer from which the features will be deleted.

FeatureIDs (string): The list of feature IDs to be removed from the dynamic layer.

 N/A

Flood Service

Flood Service

The Location Hub® Flood Service processes geographic coordinates and quickly evaluates whether an address (or coordinate location) is inside a flood hazard return period, including River Flood (Fluvial), Surface Water (Pluvial), Storm Surge, and/or Defended Areas.

The Flood Service supports the following return periods only: OneIn20Years, OneIn50Years, OneIn75Years, OneIn100Years, OneIn200Years, OneIn500Years, OneIn1500Years, SurfaceWaterOneIn20Years, SurfaceWaterOneIn50Years, SurfaceWaterOneIn75Years, SurfaceWaterOneIn100Years, SurfaceWaterOneIn200Years, SurfaceWaterOneIn500Years, SurfaceWaterOneIn1500Years, StormSurgeOneIn20Years, StormSurgeOneIn50Years, StormSurgeOneIn75Years, StormSurgeOneIn100Years, StormSurgeOneIn200Years, StormSurgeOneIn500Years, StormSurgeOneIn1500Years

What does it do?

The Flood Service allows users to determine whether or not a property is within a flood risk area or defended area based on a defined return period by passing a geographic coordinate of the location to the service. Input coordinates must be in Latitude and Longitude WGS84 projection.

The Flood Indication service quickly returns True or False if the coordinate falls within the maximum flood extent of the 1 in 1,500 year return period for either River Flood, Surface Water and/or Storm Surge. The Flood Evaluation service allows the user to specify the flood return period to be queried and the service returns the flood depth at the location, if the coordinate is within the extent. The Defended Area service returns the Standard of Protection (SoP) and the accuracy Level of the defended area polygon.

Flood Service – SOAP Interface

The SOAP Interface provides access to the following web service requests:

Flood Service – REST Interface

The REST API Interface provides access to the following web service requests:

Flood Service – Return Periods

The following Flood Return Periods are available in the Flood Evaluation Service for River Flood, Surface Water and Storm Surge:

  • 1 in 20 year
  • 1 in 50 year
  • 1 in 75 year
  • 1 in 100 year
  • 1 in 200 year
  • 1 in 500 year
  • 1 in 1,500 year

Flood Service – Depth Levels

The following depth levels are returned by the Flood Evaluation Service for River Flood, Surface Water and Storm Surge:

DEPTH CODE DEPTH DESCRIPTION
1 x <= 0.3m
2 0.3 < x <= 1m
3 1 < x <= 3m
4 3 < x <= 6m
5 6 < x <= 9m
6 x > 9m
127 No Data Found

Flood Service – Defended Area Information
The following attributes will be returned for Defended Area: (SoP, Level):

Attribute Data Type Description 
Level Integer Indicates if the Standard of Protection (SoP) and polygon areas are based on sourced data and/or assumptions.
SoP Integer Standard of Protection assigned to individual polygon areas representing a Defended Area.
This is expressed as a return period of 1 in 20 years or more.
A value of 50 indicates a Standard of Protection up to a river flood hazard return period of 1 in 50 years.

The following table explains the levels assigned to the Defended Area polygon according to the number of assumptions included:

Level Source of SoP Source of Area Polygon
0 No Data No Data
1 Assumed Assumed
2 Assumed Sourced
Sourced Assumed
3 Sourced Sourced

Accessing the Service

To access the Location Hub Flood service you must first be authorized for use with Location Hub Web Services in order to have a valid user name and password. Please contact info@dmtispatial.com for more information on how to register for the Location Hub Flood Web Service.
Once you have a valid user name and password, please refer to the Authentication section for information on how to access the service.

Elevation Service

Elevation Service

The Location Hub® Elevation Service processes geographic coordinates and quickly returns the elevation of the geographic location above sea level.

What does it do?

The Elevation Service allows users to determine the elevation of a property by passing a geographic coordinate of the location to the service. Input coordinates must be in Latitude and Longitude WGS84 projection.

Location Hub uses the Canadian Digital Elevation Data (CDED) as a reference source for the elevation service. The elevation returned by the service is in metres relative to Mean Seal Level (MSL) which is represented as 0. A response value of -9999 indicates that no data is available at the specified coordinate.

Accessing the Service

To access the Location Hub Elevation service you must first be authorized for use with Location Hub Web Services in order to have a valid user name and password. Please contact info@dmtispatial.com for more information on how to register for the Location Hub Elevation Web Service.

Once you have a valid user name and password, please refer to the Authentication section for information on how to access the service.

SOAP Service

SOAP Operations

There are 2 Elevation operation requests available through SOAP/XML

  • GetElevation: Returns the elevation in metres above Mean Sea Level for the given geographic coordinate location
  • GetElevations: Returns the elevation in metres above Mean Sea Level for a batch of geographic coordinate locations

Parameters

The following parameters are required by all Elevation Service Operations:

  • Lat (double): The WGS84 latitude of the location specified
  • Lon (double): The WGS84 longitude of the location specified

The following parameter is optional for the GetElevations operation only:

  • ID (string): an optional identifier for the coordinate location

Examples:

<!-- The SOAP/XML Request -->
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:lh="http://lh.dmtispatial.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <lh:GetElevation>
         <!--type: double-->
         <lh:lat>47.3840580627</lh:lat>
         <!--type: double-->
         <lh:lon>-53.919928273</lh:lon>
      </lh:GetElevation>
   </soapenv:Body>
</soapenv:Envelope>
 
<!-- The SOAP/XML Response -->
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
   <s:Body>
      <GetElevationResponse xmlns="http://lh.dmtispatial.com/">
         <GetElevationResult>27</GetElevationResult>
      </GetElevationResponse>
   </s:Body>
</s:Envelope>
 
<!-- The SOAP/XML Request -->
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:lh="http://lh.dmtispatial.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <lh:GetElevations>
         <lh:coords>
            <!--1 or more repetitions:-->
            <lh:Coordinate>
               <!--Optional:-->
               <!--type: string-->
               <lh:ID>1</lh:ID>
               <!--type: double-->
               <lh:Lat>47.3840580627</lh:Lat>
               <!--type: double-->
               <lh:Lon>-53.919928273</lh:Lon>
            </lh:Coordinate>
            <lh:Coordinate>
               <lh:ID>2</lh:ID>
               <lh:Lat>44.648881</lh:Lat>
               <lh:Lon>-63.575312</lh:Lon>
            </lh:Coordinate>
            <lh:Coordinate>
               <lh:ID>3</lh:ID>
               <lh:Lat>50</lh:Lat>
               <lh:Lon>-100</lh:Lon>
            </lh:Coordinate>
            <lh:Coordinate>
               <lh:ID>4</lh:ID>
               <lh:Lat>0</lh:Lat>
               <lh:Lon>0</lh:Lon>
            </lh:Coordinate>
         </lh:coords>
      </lh:GetElevations>
   </soapenv:Body>
</soapenv:Envelope>
 
<!-- The SOAP/XML Response -->
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
   <s:Body>
      <GetElevationsResponse xmlns="http://lh.dmtispatial.com/">
         <GetElevationsResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
            <Coordinate>
               <ID>1</ID>
               <Lat>47.3840580627</Lat>
               <Lon>-53.919928273</Lon>
               <Elevation>27</Elevation>
            </Coordinate>
            <Coordinate>
               <ID>2</ID>
               <Lat>44.648881</Lat>
               <Lon>-63.575312</Lon>
               <Elevation>16.923</Elevation>
            </Coordinate>
            <Coordinate>
               <ID>3</ID>
               <Lat>50</Lat>
               <Lon>-100</Lon>
               <Elevation>466</Elevation>
            </Coordinate>
            <Coordinate>
               <ID>4</ID>
               <Lat>0</Lat>
               <Lon>0</Lon>
               <Elevation>-9999</Elevation>
            </Coordinate>
         </GetElevationsResult>
      </GetElevationsResponse>
   </s:Body>
</s:Envelope>

 

REST Service

REST Operations

There is one Elevation operation request available through REST

  • elevation: Returns the elevation in metres above Mean Sea Level for the given geographic coordinate location

Parameters

The following parameters are supported by the elevation REST request:

  • coord (double,double): The WGS84 latitude and longitude pair of the location separated by a comma, i.e. (lat,lon)
  • format (optional string): the output format of the response. The options supported are json or xml. If no format is provided, the service will default to json.

Examples:

/* REST Requests with format options */
 
/rest/elevation?coord=47.3840580627,-53.919928273
/rest/elevation?coord=47.3840580627,-53.919928273&format=json
/rest/elevation?coord=47.3840580627,-53.919928273&format=xml
 
/* REST Responses with format options above */
27
27
<double xmlns="http://schemas.microsoft.com/2003/10/Serialization/">27</double>

Authentication

Authentication

Using OAuth 2.0 to access Location Hub

Location Hub uses Web Service authentication for authorization and access based on OAuth 2.0 protocol. All information transmitted to Location Hub services is encrypted using Secure Socket Layer (SSL) technology.

The Location Hub® Viewer API utilizes Basic Authentication for authorization and access of the services. Please refer to the Basic Authentication page for more details.

Basic Workflow

To summarize, the workflow is as follows:

  • Request an access token from the Authentication server using the client application’s credentials. Please contact your account executive to obtain your client credentials (client_id and client_secret).
  • Cache the authentication token for use in all requests until it expires.
  • Use the authentication token to make requests to Location Hub, until the authentication token expires. When the token has expired, the process should be repeated.

Requesting a Token

Tokens are retrieved using a simple HTTP POST request and then the token is appended to each service request in the “Authorization” HTTP header. The token request url is different for each Location Hub Service being accessed and requires the service name as part of the url. When requesting a token, the following url must be used:

Token Request url

https://dc1.spatialstream.com/ssapi/rest/v1/{service_name}/oauth2/token/

  • {service_name} – This is the specific Location Hub web service name that must be included in the token request url. Please contact your account executive to obtain your service name.

The POST request requires the following three parameters in the body of the request:

  • grant_type – This must be set to “client_credentials”
  • client_id – The unique Client ID provided by your account executive
  • client_secret – The unique Client Secret provided by your account executive

Sample HTTP POST Request

POST https://dc1.spatialstream.com/ssapi/rest/v1/recognition/oauth2/token/ HTTP/1.1
Accept-Encoding: gzip,deflate 
Content-Type: application/x-www-form-urlencoded 
Content-Length: 119 
Host: dc1.spatialstream.com 
Connection: Keep-Alive 
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

grant_type=client_credentials&client_id=clientIdrealValue&client_secret=topsecret

 

Sample HTTP POST Response

{
    "token_type": "bearer",
    "access_token": "0BqfgTJC7wZ7C2KeekssswRu8E7x1GFGG",
    "expires_in": 28800 
}

 

 Sample Token Management Code (C#)

private string tokenRequestURL= "https://dc1.spatialstream.com/ssapi/rest/v1/{service_name}/oauth2/token/";
private string clientSecret = "Client_Secret";
private string clientID = "Client_ID";
 
// {service_name} is the specific Location Hub web service name that must be included in the token request URL
 
Dictionary<string, KeyValuePair<string, DateTime>> tokens = new Dictionary<string, KeyValuePair<string, DateTime>>();
 
public string GetToken(string serviceName)
{
    lock (tokens)
    {
        private string uriAddress = tokenRequestURL.Replace("{service_name}", serviceName); 
        KeyValuePair<string, DateTime> tokenPair;
 
        if (!tokens.TryGetValue(uriAddress, out tokenPair) || tokenPair.Value < DateTime.UtcNow)
        {
            var tokenResponse = GetOAuthToken(uriAddress);
            if (tokenResponse != null)
            {
                // the returned token must be preceded with "bearer "
                string authToken = string.Format("bearer {0}", tokenResponse.Value.Key);
 
                // request new token when we are at 20% from the expiration time
                DateTime tokenExpiry = DateTime.UtcNow.AddSeconds(tokenResponse.Value.Value * 4 / 5);
 
                tokenPair = new KeyValuePair<string, DateTime>(authToken, tokenExpiry);
                tokens[uriAddress] = tokenPair;
            }
        }
 
        return tokenPair.Key;
    }
}
 
private KeyValuePair<string, int>? GetOAuthToken(string tokenRequestAddress)
{
    WebClient authClient = new WebClient();
    authClient.BaseAddress = tokenRequestAddress;
    NameValueCollection values = new NameValueCollection();
 
    values.Add("grant_type", "client_credentials");
    values.Add("client_id", clientSecret);
    values.Add("client_secret", clientID);
 
    byte[] tokenResponseInBytes = authClient.UploadValues(tokenRequestAddress, values);
    string tokenResponse = Encoding.UTF8.GetString(tokenResponseInBytes);
    dynamic token = JsonConvert.DeserializeObject(tokenResponse);
    string access_token = token["access_token"];
    int expiry = token["expires_in"];
 
    return new KeyValuePair<string, int>(access_token, expiry);
}

 

Using the Token

Once you have received the token and cached it, you can use the cached token in all calls to Location Hub by including it as the HTTP Authorization header. Attaching the token as the Authentication header can be done using the example below:

string serviceName = "recognition";
var token = GetToken(serviceName);
 
if (token != null)
    WebOperationContext.Current.OutgoingRequest.Headers[HttpRequestHeader.Authorization]
        = token;

 

The HTTP POST request would look something like this:

POST https://lhrecognition.dmtispatial.com/services/recognition/v2.2 HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: text/xml;charset=UTF-8
SOAPAction: "RecognizeFreeForm"
Authorization: bearer ***********************************
Content-Length: 1809
Host: lhrecognition.dmtispatial.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

 

Token Expiry

When a token is issued, the expires_in value in the response is the number of seconds from the time of issue that the token will be valid for. The default token expiry time is 8 hours form time of issue.

The token expiry is defined in the following response parameter:

  • expires_in: The number of seconds from the time of issue that the token will expire

It is recommended that you request a new token before the expiry time.

Address Suggest

Address Suggest

The Location Hub® Address Suggest Service provides on-the-fly data matching, saving you time and money while dramatically improving data accuracy throughout your entire operation.

What Does It Do?

The service provides “auto-completion” capability for freeform address entry, which can be quickly integrated into any process used to capture address information, such as a web application. The service predicts the possible addresses that match the input as it is being entered by a user. Only addresses validated within the DMTI Master Address Repository are returned, minimizing the risk of keying errors or an invalid address being submitted.

Address Suggest is not a replacement for Address Recognition. It is designed to complement it in interactive applications by providing “type-ahead” or “auto-completion” capability for freeform address entry. When used in combination with Address Recognition, any text entered by the user, even when Address Suggest does not return any results, should still be run through Recognition, since it has more sophisticated methods of searching for addresses and provides some distinct capabilities not available in Address Suggest. In many cases, Address Recognition service will be able to find a match.

Accessing the Service

To access the Location Hub Address Suggest service you must first be authorized for use with Location Hub Web Services in order to have a valid user name and password. Please contact info@dmtispatial.comfor more information on how to register for the Location Hub Address Suggest Web Service.

Once you have a valid user name and password, please refer to the Authentication section for information on how to access the service.

SOAP Service

SOAP Operations

Address Suggest shares the SOAP endpoint with the Address Recognition service. The operation name is Suggest and the request/response types are SuggestRequest/SuggestResponse.

  • Suggest – returns a list of possible address matches

Parameters

  • request (string): – the partial address string
  • maxSuggestions (integer): – the maximum number of possible address matches to return
  • includePostalCode (optional boolean): – option to include the postal code in the returned possible address matches
  • returnAliases (optional boolean): – option to return the next best alias in the Alias field which will typically be a Canada Post Municipality or Neighbourhood Name

Sample SOAP SuggestRequest and SuggestResponse:

<!-- SuggestRequest with returnAliases set to True -->
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v2="http://www.dmtispatial.com/recognition/v2.2/">
   <soapenv:Header/>
   <soapenv:Body>
      <v2:SuggestRequest>
         <!--type: string-->
         <v2:request>5 Byng Ave Tor</v2:request>
         <!--type: int-->
         <v2:maxSuggestions>20</v2:maxSuggestions>
         <!--Optional:-->
         <!--type: boolean-->
         <v2:includePostalCode>true</v2:includePostalCode>
         <!--Optional:-->
         <!--type: boolean-->
         <v2:returnAliases>true</v2:returnAliases>
      </v2:SuggestRequest>
   </soapenv:Body>
</soapenv:Envelope>
 
<!-- SuggestResponse with Alias -->
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
   <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
      <SuggestResponse xmlns="http://www.dmtispatial.com/recognition/v2.2/">
         <ResponseItems>
            <SuggestResult MatchCount="1" Alias="5 BYNG AVE ETOBICOKE ON M9W2M5">5 BYNG AVE TORONTO ON M9W2M5</SuggestResult>
            <SuggestResult MatchCount="1" Alias="5 BYNG AVE NORTH YORK ON M2N0E6">5 BYNG AVE TORONTO ON M2N0E6</SuggestResult>
            <SuggestResult MatchCount="1" Alias="5 BYNG AVE SCARBOROUGH ON M1L3N5">5 BYNG AVE TORONTO ON M1L3N5</SuggestResult>
         </ResponseItems>
      </SuggestResponse>
   </s:Body>
</s:Envelope>
 
 
<!-- SuggestRequest with returnAliases set to False -->
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v2="http://www.dmtispatial.com/recognition/v2.2/">
   <soapenv:Header/>
   <soapenv:Body>
      <v2:SuggestRequest>
         <!--type: string-->
         <v2:request>5 Byng Ave Tor</v2:request>
         <!--type: int-->
         <v2:maxSuggestions>20</v2:maxSuggestions>
         <!--Optional:-->
         <!--type: boolean-->
         <v2:includePostalCode>true</v2:includePostalCode>
         <!--Optional:-->
         <!--type: boolean-->
         <v2:returnAliases>false</v2:returnAliases>
      </v2:SuggestRequest>
   </soapenv:Body>
</soapenv:Envelope>
 
<!-- SuggestResponse with no Alias -->
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
   <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
      <SuggestResponse xmlns="http://www.dmtispatial.com/recognition/v2.2/">
         <ResponseItems>
            <SuggestResult MatchCount="1">5 BYNG AVE TORONTO ON M1L3N5</SuggestResult>
            <SuggestResult MatchCount="1">5 BYNG AVE TORONTO ON M2N0E6</SuggestResult>
            <SuggestResult MatchCount="1">5 BYNG AVE TORONTO ON M9W2M5</SuggestResult>
         </ResponseItems>
      </SuggestResponse>
   </s:Body>
</s:Envelope>

REST Service

REST Operations

Address Suggest also shares the REST url with the Address Recognition service. The method name is suggest :

  • suggest: – returns a list of possible address matches

Input Parameters

  • address (string): – the partial address string
  • limit (integer): – the maximum number of possible address matches to return. The service has a maximum predetermined limit of 100.
  • includePostalCode (optional boolean): – option to include the postal code in the returned possible address matches
  • returnAliases (optional boolean): – option to return the next best alias in the aliasSuggest field which will typically be a Canada Post Municipality or Neighbourhood Name
  • format (optional string): – the output format of the response. The options supported are json or xml. If no format is provided, the service will default to json.
  • provinceFilter (optional string): – option to filter results by Province. This parameter accepts a comma separated list of abbreviated Provinces and Territories: AB,BC,MB,NB,NL,NS,NT,NU,ON,PE,QC,SK,YT
  • sortByMunicipality (optional boolean): – option to sort by Municipalities with the largest population first
  • lat (optional decimal): – option to sort by proximity to a location based on Latitude and Longitude coordinates. This parameter accepts valid Latitude values.
  • lon (optional decimal): – option to sort by proximity to a location based on Latitude and Longitude coordinates. This parameter accepts valid Longitude values.

Output Response

The call to the service will return an array of objects each with three fields:

  • matchCount – number of addresses that potentially match the aggregate result.
    • When matchCount == 1, you have a “leaf node” – an actual individual address that is basically guaranteed to be able to go through recognition
    • When matchCount > 1, it’s an aggregate that basically requires more input from the user.
  • suggestion – the output address text
  • aliasSuggest – the output address text with the Canada Post Municipality or Neighbourhood Name as the Municipality
    • When returnAliases == false, then aliasSuggest is Null

Example:

When the beginning of “5 Byng Ave Toronto ON” is being typed, such as “5 Byng Ave Tor”, the following will be returned:

Sample REST Request and Response:

// Request with returnAliases = true and format = json
services/rest/V2.2/suggest?address=5%20Byng%20Ave%20Toronto&limit=20&includePostalCode=true&returnAliases=true&format=json
 
// Response in json with aliasSuggest
[
      {
      "matchCount": 1,
      "suggestion": "5 BYNG AVE TORONTO ON M9W2M5",
      "aliasSuggest": "5 BYNG AVE ETOBICOKE ON M9W2M5"
   },
      {
      "matchCount": 1,
      "suggestion": "5 BYNG AVE TORONTO ON M2N0E6",
      "aliasSuggest": "5 BYNG AVE NORTH YORK ON M2N0E6"
   },
      {
      "matchCount": 1,
      "suggestion": "5 BYNG AVE TORONTO ON M1L3N5",
      "aliasSuggest": "5 BYNG AVE SCARBOROUGH ON M1L3N5"
   }
]
 
// Request with returnAliases = false and format = json
services/rest/V2.2/suggest?address=5%20Byng%20Ave%20Toronto&limit=20&includePostalCode=true&returnAliases=false&format=json
 
// Response in json with null aliasSuggest
[
      {
      "matchCount": 1,
      "suggestion": "5 BYNG AVE TORONTO ON M1L3N5",
      "aliasSuggest": null
   },
      {
      "matchCount": 1,
      "suggestion": "5 BYNG AVE TORONTO ON M2N0E6",
      "aliasSuggest": null
   },
      {
      "matchCount": 1,
      "suggestion": "5 BYNG AVE TORONTO ON M9W2M5",
      "aliasSuggest": null
   }
]
 
 
// Request with returnAliases = true and format = xml
services/rest/V2.2/suggest?address=5%20Byng%20Ave%20Toronto&limit=20&includePostalCode=true&returnAliases=true&format=xml
 
// Response in xml with aliasSuggest
<suggestions xmlns="http://schemas.datacontract.org/2004/07/ServiceRestInterface" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
   <suggestion>
      <matchCount>1</matchCount>
      <suggestion>5 BYNG AVE TORONTO ON M9W2M5</suggestion>
      <aliasSuggest>5 BYNG AVE ETOBICOKE ON M9W2M5</aliasSuggest>
   </suggestion>
   <suggestion>
      <matchCount>1</matchCount>
      <suggestion>5 BYNG AVE TORONTO ON M2N0E6</suggestion>
      <aliasSuggest>5 BYNG AVE NORTH YORK ON M2N0E6</aliasSuggest>
   </suggestion>
   <suggestion>
      <matchCount>1</matchCount>
      <suggestion>5 BYNG AVE TORONTO ON M1L3N5</suggestion>
      <aliasSuggest>5 BYNG AVE SCARBOROUGH ON M1L3N5</aliasSuggest>
   </suggestion>
</suggestions>
 
// Request with returnAliases = false and format = xml
services/rest/V2.2/suggest?address=5%20Byng%20Ave%20Toronto&limit=20&includePostalCode=true&returnAliases=false&format=xml
 
// Response in xml with nil aliasSuggest
<suggestions xmlns="http://schemas.datacontract.org/2004/07/ServiceRestInterface" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
   <suggestion>
      <matchCount>1</matchCount>
      <suggestion>5 BYNG AVE TORONTO ON M1L3N5</suggestion>
      <aliasSuggest i:nil="true"/>
   </suggestion>
   <suggestion>
      <matchCount>1</matchCount>
      <suggestion>5 BYNG AVE TORONTO ON M2N0E6</suggestion>
      <aliasSuggest i:nil="true"/>
   </suggestion>
   <suggestion>
      <matchCount>1</matchCount>
      <suggestion>5 BYNG AVE TORONTO ON M9W2M5</suggestion>
      <aliasSuggest i:nil="true"/>
   </suggestion>
</suggestions>
 
// Request with provinceFilter=MB,SK and sortByMunicipality=true
services/rest/V2.2/suggest?address=123 Main St W&limit=50&includePostalCode=true&returnAliases=true&format=json&provinceFilter=MB,SK&sortByMunicipality=true
 
// Response in json sorted by Populated Municipalities and filtered for MB and SK
[
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W WARMAN SK S0K0A1",
        "aliasSuggest": "123 MAIN ST W WARMAN SK S0K0A1"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W LANGHAM SK S0K2L0",
        "aliasSuggest": "123 MAIN ST W LANGHAM SK S0K2L0"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W NEEPAWA MB R0J1H0",
        "aliasSuggest": "123 MAIN ST W NEEPAWA MB R0J1H0"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W GREY MB R0G0W0",
        "aliasSuggest": "123 MAIN ST W HAYWOOD MB R0G0W0"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W CHRISTOPHER LAKE SK S0J0N0",
        "aliasSuggest": "123 MAIN ST W CHRISTOPHER LAKE SK S0J0N0"
    }
]
 
// Request with Latitude and Longitude set to coordinates for Thunder Bay, ON
services/rest/v2.2/suggest?address=123 Main St W&limit=50&includePostalCode=true&returnAliases=true&format=json&lat=48.3818&lon=-89.2461
 
// Response sorted by proximity to Thunder Bay, ON
[
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W GREATER SUDBURY / GRAND SUDBURY ON P0M1L0",
        "aliasSuggest": "123 MAIN ST W CHELMSFORD ON P0M1L0"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W GREY MB R0G0W0",
        "aliasSuggest": "123 MAIN ST W HAYWOOD MB R0G0W0"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W NEEPAWA MB R0J1H0",
        "aliasSuggest": "123 MAIN ST W NEEPAWA MB R0J1H0"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W NORTH BAY ON P1B2T6",
        "aliasSuggest": "123 MAIN ST W NORTH BAY ON P1B2T6"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W GREY HIGHLANDS ON N0C1H0",
        "aliasSuggest": "123 MAIN ST W MARKDALE ON N0C1H0"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W MINTO ON N0G2P0",
        "aliasSuggest": "123 MAIN ST W PALMERSTON ON N0G2P0"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W NORTH PERTH ON N4W1A2",
        "aliasSuggest": "123 MAIN ST W LISTOWEL ON N4W1A2"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W SOUTHGATE ON L9V3K3",
        "aliasSuggest": "123 MAIN ST W SHELBURNE ON L9V3K3"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W SHELBURNE ON L9V2X8",
        "aliasSuggest": "123 MAIN ST W SHELBURNE ON L9V2X8"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W KINGSVILLE ON N9Y1H6",
        "aliasSuggest": "123 MAIN ST W KINGSVILLE ON N9Y1H6"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W NEW TECUMSETH ON L0G1A0",
        "aliasSuggest": "123 MAIN ST W BEETON ON L0G1A0"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W CHATHAM-KENT ON N0P2C0",
        "aliasSuggest": "123 MAIN ST W RIDGETOWN ON N0P2C0"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W NORWICH ON N0J1P0",
        "aliasSuggest": "123 MAIN ST W NORWICH ON N0J1P0"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W HAMILTON ON L8P1H9",
        "aliasSuggest": "123 MAIN ST W HAMILTON ON L8P1H9"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W GRIMSBY ON L3M1R9",
        "aliasSuggest": "123 MAIN ST W GRIMSBY ON L3M1R9"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W HALDIMAND COUNTY ON N1A3C8",
        "aliasSuggest": "123 MAIN ST W DUNNVILLE ON N1A3C8"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W PORT COLBORNE ON L3K3V3",
        "aliasSuggest": "123 MAIN ST W PORT COLBORNE ON L3K3V3"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W MERRICKVILLE-WOLFORD ON K0G1N0",
        "aliasSuggest": "123 MAIN ST W MERRICKVILLE ON K0G1N0"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W HAWKESBURY ON K6A2H3",
        "aliasSuggest": "123 MAIN ST W HAWKESBURY ON K6A2H3"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W CHAMPLAIN ON K0B1R0",
        "aliasSuggest": "123 MAIN ST W VANKLEEK HILL ON K0B1R0"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W CHRISTOPHER LAKE SK S0J0N0",
        "aliasSuggest": "123 MAIN ST W CHRISTOPHER LAKE SK S0J0N0"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W WARMAN SK S0K0A1",
        "aliasSuggest": "123 MAIN ST W WARMAN SK S0K0A1"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W LANGHAM SK S0K2L0",
        "aliasSuggest": "123 MAIN ST W LANGHAM SK S0K2L0"
    },
    {
        "matchCount": 1,
        "suggestion": "123 MAIN ST W SAINT JOHN NB E2M3N4",
        "aliasSuggest": "123 MAIN ST W SAINT JOHN NB E2M3N4"
    }
]

Address Recognition and Geocoding

Address Recognition and Geocoding

The Location Hub Address Recognition Service provides Canadian address recognition functionality which seeks to correct and verify addresses so that organizations can leverage the inherent value of an address with the confidence and trust they need in order to make precise business decisions.

What Does It Do?

The purpose of Address Recognition is for an address to be confirmed as an admissible, reliable address. More specifically, Location Hub’s Address Recognition Service uses advanced logic and address matching principles to standardize and correct the predominant majority of Canadian addresses – making adjustments to formatting, spelling, missing information and component standardization – so that an address can be matched against a market leading Master Address Repository for Canada. The service recognizes both civic and postal addresses – including rural routes, PO boxes and postal station information – and cross-correlates them to ensure you always get the right result for your application.

Once an address has been properly recognized, it can be geocoded – attaching latitude and longitude coordinates. The service takes you beyond approximate locations to accurately pinpoint customers and prospects with rooftop precision. For records where you don’t have an exact address, it also supports geocoding to the street, intersections, populated place or postal code. Additional context is provided about a location such as the likelihood the property exists, whether it is a single family home or multi-dwelling unit, and the property type (residential, commercial or mixed).

Each address is assigned a unique, persistent address identifier (UAID) providing unparalleled matching capabilities to ensure you can always match and link seemingly disparate addresses.

Why Is It Beneficial?

Effectively Price and Configure Products

  • Support real-time locates and serviceability determination;
  • Increase customer service levels and improve customer experience;
  • Reduce errors associated with address mismatch;
  • Resolve issues that delay delivery and service interval problems;
  • Improve productivity and efficiency measures for customer service representatives by providing them with the enhanced information needed immediately at point of contact.

Increase Addressable Market

  • Increase net adds and infill conversion rates during the campaign planning and execution process;
  • Significantly increase addressable markets by improving target address data quality for prospect lists, segmentation and customer location mapping.

Accessing the Service

To access the Location Hub Address Recognition and Geocoding service you must first be authorized for use with Location Hub Web Services in order to have a valid user name and password. Please contact info@dmtispatial.com for more information on how to register for Location Hub Address Recognition and Geocoding Web Service.

Once you have a valid user name and password, please refer to the Authentication section for information on how to access the service.

Using the Address Recognition and Geocoding Service

The Address Recognition and Geocoding service is available as both SOAP and REST web services. Please refer to the following pages for details on the services:

Address Assert

Address Assert

Address Assert is a service providing customers with the ability to “assert” addresses that are not currently available in the Location Hub database in order to be able to recognize them in future transactions.

Customers can also use the Address Assert service to add client specific attributes to existing and “asserted” addresses as required. Address Assert provides a customer specific database to maintain these addresses and attributes to ensure that each customer’s data is kept separate.

Each address that is added to the assert database will be appended with a unique GUID identifier, similar to the UAID that is associated to each address contained within Location Hub. This unique identifier is the Asserted Address ID (AAID) and can be used to return attribute information assigned to the address or to identify the address when performing additional operations.

If an asserted address contains multiple units it will also be appended with a Unit Asserted Address ID (UAAID). This UAAID can be appended to both existing addresses (those with a UAID) or asserted addresses (those with an AAID).

Address Assert contains two API interfaces to interact with the assert database and Location Hub:

Address Assert Recognition Service Interface

Address Assert requires the use of the Address Assert Recognition Service. This service should be used instead of the standard Location Hub Address Recognition service as this service contains all operations currently available in the Location Hub Address Recognition service as well as operations for use specifically with the Address Assert Service.

If implementing Address Assert, please ensure to use the Address Assert Recognition Service for all service calls to Location Hub as it will query the assert database along with Location Hub on each request. For a complete list of operations available, please refer to the Address Assert Recognition Service page.

Address Assert Service Interface

The Address Assert Service is required to interact with the assert database only. It provides operations to add, update, delete and query asserted addresses and attributes.

For a complete list of operations available, please refer to the Address Assert Service page.