Events Streaming API
Real-time event streaming API with time-windowed queries, viewport filtering, automatic response mode selection, and WebSocket subscriptions.
Last updated: 2025-02-18
Events Streaming API
The Events Streaming API provides efficient access to logistics events for map visualization, dashboards, and analytics. It automatically selects the optimal response format based on query parameters.
500 logistics events rendered from the streaming API with automatic mode selection.
Core Endpoint
/api/events/streamQuery events within a time window and viewport
Required Parameters:
| Parameter | Type | Description |
|---|---|---|
from | ISO 8601 | Start of time window |
to | ISO 8601 | End of time window |
Optional Parameters:
| Parameter | Type | Description |
|---|---|---|
minLng | number | Viewport west bound |
maxLng | number | Viewport east bound |
minLat | number | Viewport south bound |
maxLat | number | Viewport north bound |
type | string | Filter by event type (entry, exit, placement, etc.) |
warehouse | number | Filter by warehouse ID |
limit | number | Max events (default: 10000) |
Response Modes
The API automatically selects the optimal response format:
| Time Range | Event Count | Response Mode | Format |
|---|---|---|---|
| < 1 day | < 10,000 | Raw events | Individual points |
| < 1 day | > 10,000 | Spatial clusters | Grouped with count |
| 1-7 days | Any | Hourly buckets | Aggregated by hour |
| 7-30 days | Any | Daily buckets | Aggregated by day |
| > 30 days | Any | Weekly buckets | Aggregated by week |
Raw Events Response
{
"mode": "raw",
"total": 847,
"events": [
{
"id": "evt-001",
"type": "entry",
"lat": 25.6714,
"lng": -100.3097,
"timestamp": "2025-01-15T14:32:07Z",
"tu_id": "TU-2025-00042",
"operator": "carlos.mendez",
"warehouse": "Monterrey Hub"
}
]
}
Clustered Response
{
"mode": "clustered",
"total": 24500,
"clusters": [
{
"lat": 25.67,
"lng": -100.31,
"count": 342,
"types": { "entry": 120, "exit": 115, "placement": 107 }
}
]
}
Aggregated Response
{
"mode": "aggregated",
"total": 156000,
"buckets": [
{
"start": "2025-01-15T00:00:00Z",
"end": "2025-01-15T01:00:00Z",
"count": 245,
"byType": { "entry": 82, "exit": 78, "placement": 85 }
}
]
}
WebSocket Subscription
For real-time updates, subscribe to the WebSocket endpoint:
const ws = new WebSocket('wss://your-app.com/api/events/ws');
ws.onopen = () => {
ws.send(JSON.stringify({
action: 'subscribe',
filters: {
warehouse: 1,
types: ['entry', 'exit', 'placement'],
},
}));
};
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
// { type: 'event', payload: { ... } }
};
Event Types
| Type | Description | Typical Frequency |
|---|---|---|
entry | Vehicle enters facility | 50-200/day |
exit | Vehicle departs facility | 50-200/day |
placement | Asset placed in slot | 200-500/day |
removal | Asset removed from slot | 200-500/day |
verification | Supervisor verification | 100-300/day |
weighing | Scale measurement | 50-200/day |
incident | Compliance incident | 0-10/day |
motion | CCTV motion detection | 50-500/day |
Performance
| Scenario | Target Latency | Actual |
|---|---|---|
| 10k events in window | < 200ms | ~120ms |
| 50k events (clustered) | < 300ms | ~200ms |
| 100k events (aggregated) | < 400ms | ~250ms |
| 1M events (weekly buckets) | < 500ms | ~300ms |
Rate Limits
| Plan | Requests/min | Max time window |
|---|---|---|
| Free trial | 30 | 24 hours |
| Professional | 100 | 90 days |
| Enterprise | 500 | 1 year |
Client Integration
import { useEvents } from '@/hooks/useEvents';
const {
events,
clusters,
isLoading,
totalCount,
renderMode,
} = useEvents({
timeWindow: { from, to },
bounds: { minLng, minLat, maxLng, maxLat },
enabled: true,
});
// renderMode: 'raw' | 'clustered' | 'aggregated'
// Events are automatically cached with 5-min TTL
Memory Management
The client-side cache holds a maximum of 5 time slices (50MB). LRU eviction removes the least-recently-used slice when a new one loads. All pending requests are cancelled on component unmount.