Submit Workflow - Precisely Data Integrity Suite

Data Integrity Suite APIs
Product
Data_Integrity
Spatial_Analytics
Data_Enrichment
geo_addressing_1
Services
Spatial Analytics
Data Enrichment
Geo Addressing
ft:title
Data Integrity Suite APIs
ft:locale
en-US
PublicationType
pt_developer
copyrightfirst
2023
copyrightlast
2026

This endpoint allows users to submit a workflow for bulk spatial operations such as Search Nearest, Search At Location, Overlaps, and Summarize. The request must include the necessary payload for the operation and returns a workflow URL.

HTTP Request
  • URL Composition

    Base URL: https://api.cloud.precisely.com

    Bulk Analysis : /v1/spatial/bulk-operations

  • Supported Methods: POST only
  • Rate Limit (Transactions per second): 100

  • Authentication and Input Fields: Data Integrity Suite's APIs provide multiple authentication methods. Whether you want to pass the API Key and Secret directly as part of the Basic Authentication header or use bearer tokens, you can do either using the same header. The two ways of authentication are:

    1. Basic Authentication (Using API Key and secret)
    2. Bearer Token Authentication

    For more information about authentication, see How to Authenticate and follow the instructions.

Request Body Fields

The below table lists the input fields for Bulk Spatial API:

Field Type Required Description
operation String Yes The spatial operation to be performed. Possible values are:
  • SEARCH_NEAREST: Identifies the nearest locations or objects to a specified geometry based on distance or defined criteria, returning the spatial features in distance order with the distance value.
  • SEARCH_AT_LOCATION: Searches for locations or points of interest within or intersecting a defined geographic area or a buffer around a specified location.
  • OVERLAPS: Identifies spatial intersections between a specified geometry and geometries in a selected Enrich spatial table, returning the overlap geometry with the percentage and area of overlap.
  • SUMMARIZE : Generates detailed data summaries within a specified region, including total, average, minimum and maximum values for data such as population.
payload String Yes Contains parameters according to the Operation specified. Refer tables below.

Payload Parameters for all the Spatial Operations

Parameters Type Required Description
fileId String Yes File ID generated via Generate Upload URL endpoint.
tableName String Yes Name of the table containing the spatial data.
geometryFormat String No Format of the input geometry. Possible values are:
  • WKT (Default)
  • GEOJSON
  • LonLat . For example, 
    "[-122.777231, 38.009251]"
delimiter String No Delimiter used in the file. If no delimiter is provided, the default pipe separator "|" will be used. For more information, see Supported Delimiters

Payload Parameters for SEARCH_NEAREST Operation

Parameters Type Required Description
distanceAttributeName String No The name of the distance attribute to be returned in the response. This attribute is used to return the distance value from the geometry to the found nearest features. If this parameter is not specified, the response returns the default attribute name "distance".
withinDistance String Yes The distance to search around the geometry. The withinDistance must include the distance value and distance unit. The response returns values in the units specified in the request. For example, specify "10 mi" for within 10 miles or "5 km" for within 5 kilometers. The valid values for units are:
  • mi: miles
  • km: kilometers
  • ft: feet
  • m: meters
  • nm: nautical miles
maxFeatures Integer No The total number of features returned in the response. (Default value is 1)
attributes String Yes The attribute names of the table to be returned in the response. More than one attribute is defined by a comma separated list. This is a simple way of limiting the amount of information in the response to include only the information requested. Each feature in the resulting feature collection will only contain the specified attributes.
Note: If (*) is specified as a value, all the attributes of the table are returned. For example, 
"attributes": ["*"],
uomAttributeName String No The name of unit of measurement to be returned in the response. This attribute is used to return the uom specified in the request. If this parameter is not specified, the response returns the value with the default column name "uom".
inputPointAttributeName String No The name of the input point attribute to be returned in the response. This is the point on the input feature which is closest to the target feature and is used as the start point for the bearing value. If this parameter is not specified, the default name is inputPoint_x and inputPoint_y. If specified "_x" and "_y" are appended to the provided name.
targetPointAttributeName String No The name of the target point attribute to be returned in the response. This is the point on the target feature which is closest to the input feature and is used as the end point for the bearing value. If this parameter is not specified, the default name is targetPoint_x and targetPoint_y. If specified "_x" and "_y" are appended to the provided name.
bearingAttributeName String No The name of the bearing attribute to be returned in the response. The bearing is the direction to the target feature in decimal degrees where north is 0 degrees in a clockwise direction – hence east is 90 degrees and so on. If this parameter is not specified, the response returns the value with the default column name bearing.
sortOrder String No The order to sort the returned results. Used in conjunction with the sortBy parameter. Possible values are:
  • ASC: low to high (Default value if not specified)
  • DESC: high to low
sortBy String No The attribute name used to order the returned results. The results are by default ordered by distance in order of nearest to farthest. The results can be ordered by specific attribute as well. Only one attribute column can be specified.

Payload Parameters for SEARCH_AT_LOCATION Operation

Field Type Required Description
attributes String Yes The attribute names of the table to be returned in the response. More than one attribute is defined by a comma separated list. This is a simple way of limiting the amount of information in the response to include only the information requested. Each feature in the resulting feature collection will only contain the specified attributes.
Note: If (*) is specified as a value, all the attributes of the table are returned. For example, 
"attributes": ["*"],
spatialOperation String Yes The type of spatial query. Possible values are:
  • INTERSECTS: The geometry to be returned partially overlaps the specified input geometry. (Default)
  • WITHIN: The features to be returned is entirely within the specified input geometry.
  • CONTAINS: The geometry to be returned entirely contains the specified input geometry.
bufferDistance String Yes The buffered distance around the input geometry. If specified, the parameter must include the value and the measurement unit. For example, specify "100 m" to buffer the input geometry by 10 meters before performing the spatial operation. The valid distance units are:
  • mi: miles
  • km: kilometers
  • ft: feet
  • m: meters
  • nm: nautical miles
limit Integer No Maximum number of records to be returned. (Default is 10)
Note:
  • If limit value is less than maxFeatures value, offset parameter is used to access the subsequent records.
  • this is the total number of records returned for each input record. For example, if an input record intersects with 100 spatial records and limit is 10, then only the first 10 of the intersected records are returned.
sortOrder String No The order to sort the returned results. Used in conjunction with the sortBy parameter. Possible values are:
  • ASC: low to high (Default value if not specified)
  • DESC: high to low
sortBy String No The attribute name used to order the returned results. If not specified, results are ordered by primary key ('incremental_s_no') of the table.

Payload Parameters for OVERLAPS Operation

Parameters Type Required Description
attributes Array Yes The attribute names of the target table to be returned in the response. More than one attribute is defined by a comma separated list. This is a simple way of limiting the amount of information in the response to include only the information requested. Each feature in the resulting feature collection will only contain the specified attributes.
Note:
  1. If (*) is specified as a value, all the attributes of the table are returned. For example, 
    "attributes": ["*"],
  2. Only scalar values are returned - the original geometry of the target is NOT returned as the intersection geometry is returned representing the overlap.
uom String Yes The unit of measure to use when returning the total area of length of the intersection geometry. The valid distance units are:
  • mi: Miles (for lengths) or Square Miles (for areas)
  • km: Kilometers (for lengths) or Square Kilometers (for areas)
  • ft: Feet (for lengths) or Square Feet (for areas)
  • m: Meters (for lengths) or Square Meters (for areas)
  • nm: Nautical Miles (for lengths) or Square Nautical Miles (for areas)
areaAttributeName String No The name of area attribute to be returned in the response. This attribute is used to hold the area of the intersection geometry when it is a polygon. If the intersection is a line, the value is zero. If this parameter is not specified, the response returns the value with the default column name "intersectionArea".
lengthAttributeName String No The name of length attribute to be returned in the response. This attribute is used to hold the length of the intersection geometry when it is a line. If the intersection is a polygon, the value is zero. If this parameter is not specified, the response returns the value with the default column name "intersectionLength".
percentTargetAttributeName String No The name of the percent target attribute to be returned in the response. This attribute is used to hold the percentage overlap of the intersection geometry compared to the target geometry that is intersected. The percentage is either the percentage of length or area based on the type of the geometries in the request and response. If this parameter is not specified, the response returns the value with the default column name "percentageOfTarget".
percentInputAttributeName String No The name of the percent input attribute to be returned in the response. This attribute is used to hold the percentage overlap of the intersection geometry compared to the input geometry. The percentage is either the percentage of length or area based on the type of the geometries in the request and response. If this parameter is not specified, the response returns the value with the default column name "percentageOfInput".
uomAttributeName String No The name of unit of measurement to be returned in the response. This attribute is used to return the uom specified in the request. If this parameter is not specified, the value is returned with the default column name as "uom" in the response.
limit Integer No Maximum number of records to be returned. (Default is 10)
Note:
  • If limit value is less than maxFeatures value, offset parameter is used to access the subsequent records.
  • this is the total number of records returned for each input record. For example, if an input record intersects with 100 spatial records and limit is 10, then only the first 10 of the intersected records are returned.

Payload Parameters for SUMMARIZE Operation

Parameters Type Required Description
spatialOperation String Yes The type of spatial query. Possible values are:
  • intersects: The geometry to be returned partially overlaps with the specified input geometry. (Default)
  • within: The geometry to be returned is entirely within the specified input geometry.
proportionalCalculation Boolean No Determines if proportional calculations should be applied. This parameter is only applicable where the spatialOperation parameter is specified as "intersects". Possible values are:
  • true
  • false (Default)
aggregateColumns Array Yes Columns to be aggregated, grouped by additional properties. Possible values are: min, max, avg, sum

Examples

Request: SEARCH_NEAREST

https://api.cloud.precisely.com/v1/spatial/bulk-operations
{
    "operation": "SEARCH_NEAREST",
    "payload": {
        "fileId": "77fc8973-c091-4c61-b050-55a8b09ca3e5",
        "tableName": "/properties/buildings",
        "geometryFormat": "WKT",
        "delimiter": ",",
        "distanceAttributeName": "dist",
        "withinDistance": "10 mi",
        "maxFeatures": 1,
        "attributes": [
            "statecode",
            "type",
            "mapname",
            "geom"
        ],
        "limit": 100,
        "sortOrder": "ASC"
    }
}

Response: SEARCH_NEAREST

{
  "statusUrl": "https://api.cloud.precisely.com/v1/li/workflows/status/sample-workflow-id"
}