Datasets

Upload your own polygon datasets (delivery zones, sales territories, custom boundaries) and query them with the same endpoints used for system datasets.

Create a dataset

POST /v1/datasets

Creates a dataset record and returns a pre-signed upload URL. Upload your file to the URL, and the pipeline processes it automatically.

Request body

{
  "name": "My Delivery Zones",
  "filename": "zones.geojson"
}

Field	Type	Required	Description
name	string	Yes	Display name (max 255 characters)
filename	string	Yes	Original filename. Used to detect format.
slug	string	No	URL-safe identifier. Auto-generated from name if omitted.
description	string	No	Short description (max 255 characters)

Response

{
  "datasetId": "a1b2c3d4-...",
  "slug": "my-delivery-zones",
  "uploadUrl": "https://s3.amazonaws.com/...",
  "expiresIn": 900,
  "api_version": "v1"
}

Upload your file

Use the uploadUrl to upload your file directly to S3:

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @zones.geojson

The upload URL expires in 15 minutes.

Supported formats:

Format	Extension	Notes
GeoJSON	.geojson, .json	RFC 7946
Shapefile	.zip	ZIP archive containing .shp, .shx, .dbf, and .prj
KML	.kml	Keyhole Markup Language
KMZ	.kmz	Compressed KML
CSV	.csv	Must include lat and lng columns
WKT	.wkt	Well-Known Text geometry
WKB	.wkb	Well-Known Binary geometry

Processing

After upload, the pipeline validates, converts, and indexes your data. This typically takes a few seconds. Poll the dataset status to check progress:

curl -s "https://api.terranode.co/v1/datasets/DATASET_ID" \
  -H "x-api-key: YOUR_API_KEY" | jq .status

Status values: pending → processing → ready (or error).

---

Get a dataset

GET /v1/datasets/{id}

Returns dataset metadata including processing status, feature count, bounding box, and any ingestion warnings.

curl -s "https://api.terranode.co/v1/datasets/DATASET_ID" \
  -H "x-api-key: YOUR_API_KEY" | jq .

{
  "datasetId": "a1b2c3d4-...",
  "slug": "my-delivery-zones",
  "name": "My Delivery Zones",
  "status": "ready",
  "features": 847,
  "bbox": [-122.5, 37.7, -122.3, 37.9],
  "geometryType": "Polygon",
  "version": 1,
  "createdAt": "2026-03-18T12:00:00Z",
  "updatedAt": "2026-03-18T12:00:05Z",
  "api_version": "v1"
}

---

List datasets

GET /v1/datasets

Returns all datasets owned by your account.

curl -s "https://api.terranode.co/v1/datasets" \
  -H "x-api-key: YOUR_API_KEY" | jq .

---

Update a dataset

PUT /v1/datasets/{id}

Upload a new version of an existing dataset. Returns a new upload URL. Previous versions are retained for 30 days.

curl -s -X PUT "https://api.terranode.co/v1/datasets/DATASET_ID" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "zones-v2.geojson"}' | jq .

---

Delete a dataset

DELETE /v1/datasets/{id}

Permanently deletes the dataset and all its versions.

curl -s -X DELETE "https://api.terranode.co/v1/datasets/DATASET_ID" \
  -H "x-api-key: YOUR_API_KEY"

---

Querying your datasets

Once a dataset reaches ready status, query it using dataset (by slug) or dataset_id (by UUID) on any query endpoint:

# By slug
curl -s "https://api.terranode.co/v1/pip?lat=37.78&lng=-122.41&dataset=my-delivery-zones" \
  -H "x-api-key: YOUR_API_KEY" | jq .

# By dataset ID
curl -s "https://api.terranode.co/v1/pip?lat=37.78&lng=-122.41&dataset_id=a1b2c3d4-..." \
  -H "x-api-key: YOUR_API_KEY" | jq .

Dataset limits (Free tier)

• 1 custom dataset
• Up to 500 features per dataset