Nearest

Find the N nearest features in a dataset to a given coordinate. Returns features sorted by distance, measured as geodesic distance to the nearest polygon boundary (WGS84 ellipsoid).

Single query

GET /v1/nearest

Parameters

Parameter	Type	Required	Default	Description
lat	number	Yes	—	Latitude (-90 to 90)
lng	number	Yes	—	Longitude (-180 to 180)
system_dataset	string	One required	—	System dataset slug (e.g., us-counties)
dataset	string	One required	—	Your dataset slug
dataset_id	string	One required	—	Dataset UUID
n	integer	No	1	Number of results (1–20)
radius	number	No	—	Maximum distance in meters (up to 500,000)

Provide exactly one of system_dataset, dataset, or dataset_id.

Example — single nearest

curl -s "https://api.terranode.co/v1/nearest?lat=40.7128&lng=-74.006&system_dataset=us-counties" \
  -H "x-api-key: YOUR_API_KEY" | jq .

{
  "matches": [
    {
      "properties": {
        "STATEFP": "36",
        "COUNTYFP": "061",
        "GEOID": "36061",
        "NAME": "New York",
        "NAMELSAD": "New York County",
        "STUSPS": "NY",
        "STATE_NAME": "New York"
      },
      "distance_m": 1382,
      "distance_mi": 0.86
    }
  ],
  "dataset": "us-counties",
  "version": 1,
  "latency_ms": 435,
  "api_version": "v1",
  "semantics_version": "0.1.0"
}

Field	Description
matches	Array of nearest features, sorted by distance
matches[].distance_m	Geodesic distance in meters (0 if point is inside the polygon)
matches[].distance_mi	Geodesic distance in miles

Example — 5 nearest

curl -s "https://api.terranode.co/v1/nearest?lat=40.7128&lng=-74.006&system_dataset=us-counties&n=5" \
  -H "x-api-key: YOUR_API_KEY" | jq .

Example — with radius filter

Only return features within 5 km:

curl -s "https://api.terranode.co/v1/nearest?lat=40.7128&lng=-74.006&system_dataset=us-counties&n=10&radius=5000" \
  -H "x-api-key: YOUR_API_KEY" | jq .

Features beyond the radius are excluded from results. If no features fall within the radius, matches is an empty array.

Distance measurement

Distances are geodesic measurements on the WGS84 ellipsoid using Karney’s algorithm — the same math as PostGIS ST_Distance_Spheroid. For polygon datasets, distance is measured to the nearest point on the polygon boundary. A distance of 0 means the query point is inside the polygon.

---

Batch query

POST /v1/nearest/batch

Send multiple points in a single request. See Batch Requests for input formats.

Parameters (query string)

Parameter	Type	Required	Default	Description
system_dataset	string	One required	—	System dataset slug
dataset	string	One required	—	Your dataset slug
dataset_id	string	One required	—	Dataset UUID
n	integer	No	1	Number of results per point (1–20)
radius	number	No	—	Maximum distance in meters
format	string	No	json	Response format: json or csv

Example

curl -s -X POST "https://api.terranode.co/v1/nearest/batch?system_dataset=us-counties" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {"lat": 40.7128, "lng": -74.006, "id": "nyc"},
    {"lat": 34.0522, "lng": -118.2437, "id": "la"}
  ]' | jq .

Batch limits

Up to 100 points per request on the Free tier. Each point counts as one request against your monthly quota.