POST /v1/spatial/query — Spatial Queries Reference

The spatial query endpoint returns current ground truth observations from Vangrid edge nodes within your specified area of interest (AOI). Use it to retrieve verified spatial intelligence on demand for any authorized geographic region.

All endpoint URLs, request examples, and sample responses on this page are illustrative. The Vangrid API is not yet publicly available — contact us to join early access.

Endpoint

POST https://api.vangrid.io/v1/spatial/query

Request

Headers

Header	Value
`Authorization`	`Bearer your-api-key`
`Content-Type`	`application/json`

Body parameters

aoi

object

required

GeoJSON geometry defining the area of interest. Supports Point, Polygon, and MultiPolygon types. Maximum polygon area is 100 km².

min_ground_truth_score

number

Minimum ground truth confidence score (0.0–1.0). Observations below this threshold are excluded. Defaults to 0.5.

observation_types

array

Filter by observation type. Possible values: obstacle, occupancy, change, structure, vehicle, vegetation. If omitted, all types are returned.

max_age_seconds

integer

Maximum age of observations in seconds. Defaults to 60. Use 0 for observations captured within the last second only.

limit

integer

Maximum number of observations to return. Defaults to 100, maximum 1000.

Example request

curl -X POST https://api.vangrid.io/v1/spatial/query \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "aoi": {
      "type": "Polygon",
      "coordinates": [[
        [-122.4194, 37.7749],
        [-122.4094, 37.7749],
        [-122.4094, 37.7849],
        [-122.4194, 37.7849],
        [-122.4194, 37.7749]
      ]]
    },
    "min_ground_truth_score": 0.75,
    "observation_types": ["obstacle", "vehicle"],
    "max_age_seconds": 30,
    "limit": 50
  }'

Response

Response fields

query_id

string

Unique identifier for this query, useful for support requests.

node_count

integer

Number of edge nodes that contributed observations to this response.

observations

array

Array of ground truth observation objects.

Show Observation object fields

observation_id

string

Unique identifier for this observation.

geometry

object

GeoJSON geometry of the observed feature.

observation_type

string

Classification of the observation.

ground_truth_score

number

Confidence score from 0.0 to 1.0.

timestamp

string

ISO 8601 UTC timestamp of capture.

provenance_hash

string

Cryptographic proof of data origin.

node_count

integer

Number of nodes that corroborated this observation.

Example response

{
  "query_id": "qry_9e2f1a7c",
  "node_count": 47,
  "observations": [
    {
      "observation_id": "obs_3b8d2f1a",
      "geometry": {
        "type": "Point",
        "coordinates": [-122.4150, 37.7800]
      },
      "observation_type": "vehicle",
      "ground_truth_score": 0.94,
      "timestamp": "2026-05-22T10:14:33.412Z",
      "provenance_hash": "sha256:a3f8e2c1b4d7f9e0a2b5c8d1e4f7a0b3c6d9e2f5",
      "node_count": 12
    }
  ]
}

Error responses

Status	Error code	Description
`400`	`invalid_geometry`	AOI is not valid GeoJSON
`400`	`aoi_too_large`	AOI polygon exceeds 100 km²
`401`	`unauthorized`	Missing or invalid API key
`403`	`region_not_authorized`	AOI outside authorized regions
`429`	`rate_limit_exceeded`	Too many requests

​Endpoint

​Request

​Headers

​Body parameters

​Example request

​Response

​Response fields

​Example response

​Error responses

Endpoint

Request

Headers

Body parameters

Example request

Response

Response fields

Example response

Error responses