Back to Projects

WebSocket Visitors API

Real-time visitor tracking using Bun's native WebSocket support. Broadcasts location updates to all connected clients.

Endpoint

WSws://[host]/api/visitors

WebSocket connection for real-time visitor tracking. Uses Bun's native WebSocket implementation for optimal performance.

Event Types

"initial"

Sent on connection with current visitor list

"connect"

Broadcast when a new visitor connects

"disconnect"

Broadcast when a visitor disconnects (30s delay)

"update"

Broadcast for visitor location updates

Message Schema

typestring"initial" | "connect" | "disconnect" | "update"
visitorobject (optional)Single visitor for connect/disconnect events
visitorsarray (optional)All visitors for initial event
statsobject{ totalVisitors: number, countries: number }

Visitor Object

idstringUnique visitor identifier
latnumberLatitude (city-level approximation)
lngnumberLongitude (city-level approximation)
citystringCity name
countrystringCountry name
timestampnumberUnix timestamp (ms)

🧪 Try It Live

Disconnected

🔒 Privacy: Only city-level location is stored. No precise coordinates or personal data is collected. IP geolocation via ip-api.com.

Example Usage (JavaScript)

const ws = new WebSocket('wss://beanola.com/api/visitors');

ws.onopen = () => {
  console.log('Connected to visitor tracking');
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  
  switch (data.type) {
    case 'initial':
      console.log('Current visitors:', data.visitors);
      break;
    case 'connect':
      console.log('New visitor from:', data.visitor.city);
      break;
    case 'disconnect':
      console.log('Visitor left:', data.visitor.id);
      break;
  }
  
  console.log('Stats:', data.stats);
};

ws.onclose = () => {
  console.log('Disconnected');
};

Example Message (Initial)

{
  "type": "initial",
  "visitors": [
    {
      "id": "visitor-1706180400000-abc123",
      "lat": -15.4167,
      "lng": 28.2833,
      "city": "Lusaka",
      "country": "Zambia",
      "timestamp": 1706180400000
    }
  ],
  "stats": {
    "totalVisitors": 1,
    "countries": 1
  }
}

See visitors on an interactive 3D globe

View Live Globe