> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vangrid.io/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /v1/spatial/query — Spatial Queries Reference

> POST /v1/spatial/query — Query real-time ground truth for a geographic area of interest. Accepts GeoJSON geometry, returns verified spatial observations.

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.

<Note>
  All endpoint URLs, request examples, and sample responses on this page are illustrative. The Vangrid API is not yet publicly available — [contact us](mailto:hello@vangrid.io) to join early access.
</Note>

## Endpoint

```text theme={null}
POST https://api.vangrid.io/v1/spatial/query
```

## Request

### Headers

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

### Body parameters

<ParamField body="aoi" type="object" required>
  GeoJSON geometry defining the area of interest. Supports `Point`, `Polygon`, and `MultiPolygon` types. Maximum polygon area is 100 km².
</ParamField>

<ParamField body="min_ground_truth_score" type="number">
  Minimum ground truth confidence score (0.0–1.0). Observations below this threshold are excluded. Defaults to `0.5`.
</ParamField>

<ParamField body="observation_types" type="array">
  Filter by observation type. Possible values: `obstacle`, `occupancy`, `change`, `structure`, `vehicle`, `vegetation`. If omitted, all types are returned.
</ParamField>

<ParamField body="max_age_seconds" type="integer">
  Maximum age of observations in seconds. Defaults to `60`. Use `0` for observations captured within the last second only.
</ParamField>

<ParamField body="limit" type="integer">
  Maximum number of observations to return. Defaults to `100`, maximum `1000`.
</ParamField>

### Example request

```bash theme={null}
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

<ResponseField name="query_id" type="string">
  Unique identifier for this query, useful for support requests.
</ResponseField>

<ResponseField name="node_count" type="integer">
  Number of edge nodes that contributed observations to this response.
</ResponseField>

<ResponseField name="observations" type="array">
  Array of ground truth observation objects.

  <Expandable title="Observation object fields">
    <ResponseField name="observation_id" type="string">
      Unique identifier for this observation.
    </ResponseField>

    <ResponseField name="geometry" type="object">
      GeoJSON geometry of the observed feature.
    </ResponseField>

    <ResponseField name="observation_type" type="string">
      Classification of the observation.
    </ResponseField>

    <ResponseField name="ground_truth_score" type="number">
      Confidence score from 0.0 to 1.0.
    </ResponseField>

    <ResponseField name="timestamp" type="string">
      ISO 8601 UTC timestamp of capture.
    </ResponseField>

    <ResponseField name="provenance_hash" type="string">
      Cryptographic proof of data origin.
    </ResponseField>

    <ResponseField name="node_count" type="integer">
      Number of nodes that corroborated this observation.
    </ResponseField>
  </Expandable>
</ResponseField>

### Example response

```json theme={null}
{
  "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              |