Batch Requests

Batch endpoints accept multiple points in a single request. Available on:

Input formats

The API detects the input format from the Content-Type header.

JSON array (default)

Content-Type: application/json

[
  {"lat": 40.7128, "lng": -74.006, "id": "nyc"},
  {"lat": 34.0522, "lng": -118.2437, "id": "la"}
]

Each object must have lat and lng. Any other fields are passed through in the response as-is — use this to attach your own identifiers, record IDs, or metadata to each result.

GeoJSON FeatureCollection

Content-Type: application/geo+json

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {"type": "Point", "coordinates": [-74.006, 40.7128]},
      "properties": {"id": "nyc"}
    },
    {
      "type": "Feature",
      "geometry": {"type": "Point", "coordinates": [-118.2437, 34.0522]},
      "properties": {"id": "la"}
    }
  ]
}

Note: GeoJSON coordinates are [lng, lat] (longitude first), which is the opposite of the JSON array format.

CSV

Content-Type: text/csv

id,lat,lng
nyc,40.7128,-74.006
la,34.0522,-118.2437

The CSV must include lat and lng columns. Column order doesn’t matter. Additional columns are passed through in results.

NDJSON (newline-delimited JSON)

Content-Type: application/x-ndjson

{"lat": 40.7128, "lng": -74.006, "id": "nyc"}
{"lat": 34.0522, "lng": -118.2437, "id": "la"}

One JSON object per line. Useful for streaming or large batch files.

Output formats

By default, batch responses are JSON. Add ?format=csv to get CSV output instead.

JSON output (default)

The full response object with all fields. See each endpoint’s documentation for the exact shape.

CSV output

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

CSV output flattens the response — your passthrough properties and the matched polygon’s properties appear as columns.

Passthrough properties

Any fields beyond lat and lng in your input are echoed back in the response. This lets you match results back to your source data without maintaining a separate lookup.

Input:

[{"lat": 40.7128, "lng": -74.006, "id": "nyc", "priority": "high"}]

Output (in each result’s input):

{"lat": 40.7128, "lng": -74.006, "id": "nyc", "priority": "high"}

Batch counting

Each point in a batch counts as one request against your monthly quota. A 100-point batch uses 100 of your monthly requests.

Batch limits

Up to 100 points per request on the Free tier.