Streaming

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 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

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

Body parameters

object

required

GeoJSON geometry defining the zone to monitor. Supports Polygon and MultiPolygon. Maximum area is 50 km².

number

Filter events to those above this confidence threshold. Defaults to 0.5.

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
  }'

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

string

Unique identifier for this event.

string

ISO 8601 UTC timestamp when the observation was captured.

object

GeoJSON geometry of the observed feature.

string

Classification of the observation.

number

Confidence score (0.0–1.0) based on multi-node corroboration.

integer

Number of edge nodes that contributed to this observation.

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.

Overview

API reference

Endpoint

Request

Headers

Body parameters

Example, open a stream

Stream events

Event fields

Heartbeat events

Connection limits and reconnection

​Endpoint

​Request

​Headers

​Body parameters

​Example, open a stream

​Stream events

​Event fields

​Heartbeat events

​Connection limits and reconnection

Endpoint

Request

Headers

Body parameters

Example, open a stream

Stream events

Event fields

Heartbeat events

Connection limits and reconnection