The Location Hub Viewer Point in Polygon service processes a geographic coordinate and quickly returns the region (KML polygon) the point falls within along with the attributes of the polygon. Developers can query any KML polygon layer that has been uploaded and stored in the Location Hub Viewer platform.

What does it do?

The Location Hub Viewer Point in Polygon service allows users to determine whether or not a location is within a Location Hub Viewer polygon layer (region, sales territory, risk zone, etc.) by passing a geographic coordinate of the location to the service. The polygon layer must have been uploaded as a KML layer and stored in the Location Hub Viewer platform and the name of the KML file must be provided as an input parameter. The input coordinates must be in Latitude and Longitude WGS84 projection.

The Location Hub Viewer Point in Polygon service returns a GeoJSON feature collection of zero, one, or multiple polygons from the given layer which contain the given coordinate. Each polygon will contain the geometry of the polygon, as well as all the attributes associated to the polygon. Please see http://geojson.org/ for full specifications of the GeoJSON format.

The Location Hub Viewer Point in Polygon service is only available using REST. SOAP/XML is not supported.

Accessing the Service

To access the Location Hub Viewer Point in Polygon service you must first be authorized for use with the Location Hub Viewer product 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 Viewer Point in Polygon Service.

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

REST Service

REST Operation

The following Point in Polygon service request is available through REST only:
  • GetFeatures?layer={layer}&lat={lat}&lon={lon}: Accepts a layer name and a single coordinate location as input and returns the polygon geometry at that coordinate in GeoJSON format along with all of its attributes.
    • layer (string): The name of the polygon layer to query against
    • lat (double): The WGS84 latitude of the location specified
    • lon (double): The WGS84 longitude of the location specified

Errors Messages

The Location Hub Viewer Point in Polygon service will return all errors through the following standard HTTP status codes:
  • 401 Unauthorized
    • This error code will be returned when the service was unable to authenticate the user. Make sure that the proper user name and password was provided through the HTTP header.
  • 400 Bad Request
    • This error code will be returned when the parameters provided to the services are not properly formatted.
  • 404 Not Found
    • This error code will be returned when the service was unable to find the layer name provided.
  • 200 OK
    • This code will be returned, along with the GeoJSON feature collection when successful.
    • Note that an empty feature collection will be returned if point does not lie within any polygons.

Examples:

<!-- REST Request -->
https://<PointInPoly_url>/services/v1/GetFeatures?layer=FSA_Ontario.kml&lat=43.850174&lon=-79.363277
 
<!-- REST Responses in JSON -->
{
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "id": "1",
            "geometry": {
                "type": "Polygon",
                "coordinates": [
                    [
                        [
                            -79.325408,
                            43.88045
                        ],
                        [
                            -79.326918,
                            43.880751
                        ],
                        ...
                        ...
                        ...
                        [
                            -79.325408,
                            43.88045
                        ]
                    ]
                ]
            },
            "properties": {
                "UID": "324DC175-49A9-4AFF-8385-A99B1E3167F4",
                "FSA": "L3R",
                "PROV": "ON",
                "LONGITUDE": "-79.3125234675381",
                "LATITUDE": "43.8655324729781",
                "VINTAGE": "2015.2"
            }
        }
    ]
}