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.
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/stream
\n) events as they arrive. The client reads the response body as a stream.
Request
| Header | Value |
|---|
Authorization | Bearer your-api-key |
Content-Type | application/json |
Body parameters
GeoJSON geometry defining the zone to monitor. Supports Polygon and MultiPolygon. Maximum area is 50 km².
Filter events to those above this confidence threshold. Defaults to 0.5.
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
}'
import requests
import json
API_KEY = "your-api-key"
aoi = {
"type": "Polygon",
"coordinates": [[
[-122.4194, 37.7749],
[-122.4094, 37.7749],
[-122.4094, 37.7849],
[-122.4194, 37.7849],
[-122.4194, 37.7749]
]]
}
with requests.post(
"https://api.vangrid.io/v1/spatial/stream",
headers={"Authorization": f"Bearer {API_KEY}"},
json={"aoi": aoi, "min_ground_truth_score": 0.75},
stream=True
) as response:
for line in response.iter_lines():
if line:
event = json.loads(line)
print(event)
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
Unique identifier for this event.
ISO 8601 UTC timestamp when the observation was captured.
GeoJSON geometry of the observed feature.
Classification of the observation.
Confidence score (0.0–1.0) based on multi-node corroboration.
Number of edge nodes that contributed to this observation.
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"}
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. 
