Spatial Analysis

Search nearby locations

Identifies nearest features from a table relative to an input geometry or address, within a required search distance. Supports result limiting, attribute filtering, custom distance/unit column names, and custom inputPoint/targetPoint/bearing attribute names. By default, results are ordered from nearest to farthest distance, with optional sortBy/sortOrder override.

post/v1/spatial/findNearest

Request

  • Base URL: https://api.cloud.precisely.com
  • URL: https://api.cloud.precisely.com/v1/spatial/findNearest
  • Auth: one of:
    • bearerAuth (a scheme the document does not define)
    • ApiKeyAuth (a scheme the document does not define)

Query parameters

sortBystring

Single attribute used to order returned results. If omitted, ordering is by computed distance.

sortOrderstring

Sort direction. Allowed values: ASC, ASCENDING, DESC, DESCENDING. Default: ASC.

limitinteger

Maximum number of records returned. Min 1, max 1000, default 10.

offsetinteger

Offset applied to limit. Default 0.

Headers

X-Request-Idstring

The X-Request-Id header is optional but helpful for tracking requests. It acts as a unique identifier for troubleshooting and debugging issues effectively. Maximum length: 38 characters.Example: e02f00d5-e3a9-4fd6-aen1-3e5451abee46

Request body

tableNamestring required

Name of the table containing spatial data used by the operation.

attributeFilterstring

Optional scalar attribute filter expression using logical operators (AND/OR/NOT) and comparison operators such as =, <>, <, <=, >, >=, IS NULL, LIKE, BETWEEN, and IN.

distanceAttributeNamestring

Custom name for the response distance attribute between input and target geometries. Default value is "distance".

withinDistancestring required

Distance around the input geometry used for nearest search. Include both value and unit, for example "10 mi" or "5 km". Allowed units: mi, km, ft, m, nm.

attributesstring[] required

List of table attributes to include in the response. Use ["*"] to return all attributes.

maxFeaturesinteger

Maximum number of features returned for each input geometry. Default value is 1; minimum is 1.

uomAttributeNamestring

Custom name for the response unit-of-measure attribute. Default value is "uom".

inputPointAttributeNamestring

Custom base name for input-point coordinates in the response. The service appends _x and _y. Default base name is "inputPoint".

targetPointAttributeNamestring

Custom base name for target-point coordinates in the response. The service appends _x and _y. Default base name is "targetPoint".

bearingAttributeNamestring

Custom name for the response bearing attribute. Bearing is decimal degrees from input point to target point where north is 0 and values increase clockwise.

Example request

{
  "tableName": "/risks/flood_risk",
  "location": {
    "format": "wkt",
    "value": "\"geometry\": \"POLYGON(((-96.8,30.5),(-97.7,30.5),\n(-97.7,29.9),(-96.8,29.9),(-96.8,30.5)))\"",
    "country": "USA"
  },
  "attributeFilter": "rms_err < 50",
  "distanceAttributeName": "dist",
  "withinDistance": "\"10 mi\"",
  "attributes": [
    "id",
    "name",
    "location"
  ],
  "maxFeatures": 5,
  "uomAttributeName": "measurementUnit",
  "inputPointAttributeName": "ip",
  "targetPointAttributeName": "tp",
  "bearingAttributeName": "bearingAngle"
}

Response

Successful retrieval of find nearest operations

Changes

No recorded changes to this operation across all 1 revision of this API.