---
title: "Spatial join (batch point enrichment)"
method: POST
path: "/v1/spatial-join"
tags: ["Spatial Queries"]
---

# Spatial join (batch point enrichment)

`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`

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.

## Query parameters

- `system_dataset` string
- `dataset` string
- `dataset_id` string, uuid
- `version` integer
- `format` 'json' | 'csv'
- `async` 'true'
- `webhook_url` string, uri
- `points_system_dataset` string
- `points_dataset` string
- `points_dataset_id` string, uuid
- `join_type` 'intersects' | 'within'
- `match_mode` 'first' | 'all'
- `radius` number

## Request body

- BatchInputPoint[]: Array of point objects. Also accepts a GeoJSON FeatureCollection with Point geometries (coordinates are extracted automatically).
  - `lat` number, required
  - `lng` number, required

## Response `200`

Synchronous spatial join result.

- SpatialJoinResponse
  - `summary` SpatialJoinSummary, required
    - `total` integer, required
    - `matched` integer, required
    - `unmatched` integer, required
  - `dataset` string, required
  - `version` integer, required
  - `join_type` 'intersects' | 'within', required
  - `match_mode` 'first' | 'all', required
  - `results` SpatialJoinResult[], required
    - `index` integer, required: Zero-based index of the input point.
    - `input` object, required
    - `match` boolean, required
    - `match_count` integer, required
    - `matches` SpatialJoinMatch[], required
      - `properties` FeatureProperties, required: Key-value properties from the matched feature. Keys and values depend on the dataset.
      - `on_boundary` boolean, required: True if the point lies on the polygon boundary.
      - `distance_m` number, required: Distance in meters. 0 for exact matches, >0 for radius matches.
      - `distance_mi` number, required: Distance in miles.
  - `latency_ms` number, required
  - `api_version` string, required
  - `semantics_version` string, required

## Other responses

- `202`: Async job accepted.
- `400`: Invalid request parameters or body.
- `401`: Missing or invalid API key.
- `404`: Resource not found.
- `429`: Monthly request quota exceeded.
- `500`: Internal server error.

---

[API](https://skmtc.dev/terranode/apis/terranode-geospatial-api.md) · [All operations](https://skmtc.dev/terranode/apis/terranode-geospatial-api/llms.txt) · [OpenAPI document](https://skmtc.dev/terranode/apis/terranode-geospatial-api/revisions/bdd80613bc7a?raw)