Spatial Queries

Spatial join (batch point enrichment)

Enrich points with properties from spatial features they match. Supports polygon targets (PIP containment), point targets, and line targets (distance-based matching). Configurable join type, match mode, and radius expansion. For non-polygon targets, radius is required for practical results — without it, only exact intersections match. Points can be provided in the request body or referenced from an existing point dataset.

post/v1/spatial-join

Request

  • Base URL: https://api.terranode.co
  • URL: https://api.terranode.co/v1/spatial-join
  • Auth: API key in header x-api-key

Query parameters

system_datasetstring

System dataset slug (e.g., "us-counties"). Exactly one of system_dataset, dataset, or dataset_id is required.

datasetstring

User dataset slug. Exactly one of system_dataset, dataset, or dataset_id is required.

dataset_idstring uuid

User dataset UUID. Exactly one of system_dataset, dataset, or dataset_id is required.

versioninteger

Specific dataset version to query. Defaults to the latest version.

format'json' | 'csv'

Response output format.

async'true'

Set to "true" to submit as an asynchronous batch job. Returns a job ID for polling via GET /v1/jobs/{job_id}.

webhook_urlstring uri

URL to receive a webhook notification when the async job completes.

points_system_datasetstring

System dataset slug to use as the point source instead of the request body. The referenced dataset must contain Point geometries.

points_datasetstring

User dataset slug to use as the point source instead of the request body. The referenced dataset must contain Point geometries.

points_dataset_idstring uuid

User dataset UUID to use as the point source instead of the request body. The referenced dataset must contain Point geometries.

join_type'intersects' | 'within'

Spatial predicate. "intersects" matches points inside or on the boundary. "within" matches only points strictly inside.

match_mode'first' | 'all'

"first" returns the first matching feature per point (closest, for non-polygon targets). "all" returns every matching feature.

radiusnumber

Expand search area by this radius in meters. For polygon targets, includes nearby polygons the point is not inside. For point and line targets, matches features within this distance. Maximum 500,000 m (500 km).

Request body

latnumber required
lngnumber required

Response

Synchronous spatial join result.

datasetstring required
versioninteger required
join_type'intersects' | 'within' required
match_mode'first' | 'all' required
latency_msnumber required
api_versionstring required
semantics_versionstring required

Changes

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