Point in Polygon

Determine which polygon in a dataset contains a given latitude/longitude coordinate. Returns the matching feature’s properties, or the nearest feature if no polygon contains the point.

Single query

GET /v1/pip

Parameters

Parameter	Type	Required	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

Provide exactly one of system_dataset, dataset, or dataset_id.

Example

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

Response — match found

{
  "match": true,
  "matches": [
    {
      "properties": {
        "STATEFP": "36",
        "COUNTYFP": "061",
        "GEOID": "36061",
        "NAME": "New York",
        "NAMELSAD": "New York County",
        "STUSPS": "NY",
        "STATE_NAME": "New York",
        "LSAD": "06",
        "ALAND": 58683879,
        "AWATER": 29010416
      },
      "boundary": false
    }
  ],
  "dataset": "us-counties",
  "version": 1,
  "latency_ms": 3,
  "api_version": "v1",
  "semantics_version": "0.1.0"
}

Field	Description
match	true if the point is inside at least one polygon
matches	Array of matching polygons with their properties
matches[].boundary	true if the point falls exactly on the polygon boundary
version	Dataset version used for the query
latency_ms	Server-side processing time

Response — no match (nearest fallback)

When the point doesn’t fall inside any polygon (e.g., a point in the ocean), the API returns the nearest feature with distance:

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

{
  "match": false,
  "matches": [],
  "nearest": {
    "properties": {
      "GEOID": "72049",
      "NAME": "Culebra",
      "NAMELSAD": "Culebra Municipio"
    },
    "distance_m": 7406069.6,
    "distance_mi": 4601.92
  },
  "dataset": "us-counties",
  "version": 1,
  "api_version": "v1"
}

Edge case: point on boundary

A point exactly on a polygon boundary is considered inside (covers semantics). If the point sits on a shared boundary between two polygons, both features are returned in the matches array, each with boundary: true.

---

Batch query

POST /v1/pip/batch

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

Parameters (query string)

Parameter	Type	Required	Description
system_dataset	string	One required	System dataset slug
dataset	string	One required	Your dataset slug
dataset_id	string	One required	Dataset UUID
format	string	No	Response format: json (default) or csv

Example — JSON input

curl -s -X POST "https://api.terranode.co/v1/pip/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 .

Example — CSV input

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

Batch limits

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