Skip to main content

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.

The Vangrid Streaming API delivers a continuous, real-time feed of ground truth events for a geographic zone you define. Unlike polling the spatial query endpoint, streaming gives you push-based updates the moment new observations are available from the edge network — essential for autonomous systems, live monitoring dashboards, and world model pipelines.

​
Endpoint

POST https://api.vangrid.io/v1/spatial/stream
The connection stays open and the server pushes newline-delimited JSON (\n) events as they arrive. The client reads the response body as a stream.

​
Request

​
Headers

HeaderValue
AuthorizationBearer your-api-key
Content-Typeapplication/json

​
Body parameters

​
aoi
object
required
GeoJSON geometry defining the zone to monitor. Supports Polygon and MultiPolygon. Maximum area is 50 km².
​
min_ground_truth_score
number
Filter events to those above this confidence threshold. Defaults to 0.5.
​
observation_types
array
Limit events to specific observation types. If omitted, all types are streamed.

​
Example — open a stream

curl -X POST https://api.vangrid.io/v1/spatial/stream \
  -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
  }'

​
Stream events

Each line in the stream is a JSON object representing a single ground truth event: 
{
  "event_id": "evt_8f3a2c1d",
  "timestamp": "2026-05-22T10:14:33.412Z",
  "geometry": {
    "type": "Point",
    "coordinates": [-122.4150, 37.7800]
  },
  "observation_type": "vehicle",
  "ground_truth_score": 0.94,
  "node_count": 12,
  "provenance_hash": "sha256:a3f8e2c1b4d7f9e0a2b5c8d1e4f7a0b3c6d9e2f5"
}

​
Event fields

​
event_id
string
Unique identifier for this event.
​
timestamp
string
ISO 8601 UTC timestamp when the observation was captured.
​
geometry
object
GeoJSON geometry of the observed feature.
​
observation_type
string
Classification of the observation.
​
ground_truth_score
number
Confidence score (0.0–1.0) based on multi-node corroboration.
​
node_count
integer
Number of edge nodes that contributed to this observation.
​
provenance_hash
string
Cryptographic proof of data origin, verifiable via the provenance endpoint.

​
Heartbeat events

Every 30 seconds with no new observations, the server sends a heartbeat to keep the connection alive: 
{"type": "heartbeat", "timestamp": "2026-05-22T10:15:03.000Z"}
Skip heartbeat events in your processing logic by checking event.get("type") == "heartbeat".

​
Connection limits and reconnection

  • Maximum one concurrent stream per API key by default
  • Streams time out after 24 hours; reconnect to resume
  • On disconnect, reconnect immediately — no data is buffered server-side during disconnection
Data is not buffered if your client disconnects. Events that arrive while you are disconnected are not replayed. Design your system to tolerate gaps and rely on the spatial query endpoint to backfill if needed.
Contact hello@vangrid.io to request higher concurrent stream limits or dedicated streaming infrastructure for production deployments.