Spatial queries

The API is in early access and is not publicly available. Endpoint URLs, request examples and sample responses on this page are illustrative. Contact hello@vangrid.io to request access.

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.

Endpoint

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

Request

Headers

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

Body parameters

object

required

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

number

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

array

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

integer

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

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

string

Unique identifier for this query, useful for support requests.

integer

Number of edge nodes that contributed observations to this response.

array

Array of ground truth observation objects.

Show Observation object fields

string

Unique identifier for this observation.

object

GeoJSON geometry of the observed feature.

string

Classification of the observation.

number

Confidence score from 0.0 to 1.0.

string

ISO 8601 UTC timestamp of capture.

string

Cryptographic proof of data origin.

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

Overview

API reference

Spatial queries

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

Endpoint

Request

Headers

Body parameters

Example request

Response

Response fields

Example response

Error responses