🔌 API Reference

https://livewebtraffic.com/api

POST /api/register

Register a new website and receive a unique tracking code.

Request Body

Parameter	Type	Required	Description
url	String	Yes	Your website URL
email	String	No	Contact email (optional)

Example Request

fetch('https://livewebtraffic.com/api/register', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    url: 'https://mywebsite.com',
    email: 'contact@mywebsite.com'
  })
})
.then(res => res.json())
.then(data => console.log(data));

Success Response (200)

{
  "success": true,
  "trackingCode": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "url": "https://mywebsite.com",
  "scriptTag": "<script src=\"https://livewebtraffic.com/dist/widget.bundle.js\"></script>..."
}

Error Response (400)

{
  "success": false,
  "error": "URL is required"
}

GET /api/history/:trackingCode

Retrieve visitor history for a specific tracking code.

URL Parameters

Parameter	Type	Description
trackingCode	String	Your unique tracking code

Example Request

fetch('https://livewebtraffic.com/api/history/a1b2c3d4-e5f6-7890-abcd-ef1234567890')
  .then(res => res.json())
  .then(data => console.log(data));

Success Response (200)

{
  "hits": [
    {
      "ts": 1703529600000,
      "ip": "192.168.1.1",
      "city": "New York",
      "country": "US",
      "lat": 40.7128,
      "lon": -74.0060,
      "referrer": "google.com",
      "path": "/",
      "ua": "Mozilla/5.0..."
    }
  ]
}

GET /api/history

Retrieve all visitor history across all sites (admin only - future feature).

Example Request

fetch('https://livewebtraffic.com/api/history')
  .then(res => res.json())
  .then(data => console.log(data));

Success Response (200)

{
  "hits": [
    {
      "trackingCode": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "ts": 1703529600000,
      "ip": "192.168.1.1",
      "city": "New York",
      "country": "US"
    }
  ]
}

WS WebSocket Connection

Connect to real-time visitor stream using WebSocket.

Connection URL

wss://livewebtraffic.com?code=YOUR_TRACKING_CODE

Query Parameters

Parameter	Type	Required	Description
code	String	Yes	Your tracking code (filters events to your site only)

Example Connection

const ws = new WebSocket('wss://livewebtraffic.com?code=a1b2c3d4-e5f6-7890-abcd-ef1234567890');

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

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received:', data);
};

ws.onerror = (error) => {
  console.error('WebSocket error:', error);
};

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

Message Types

1. Welcome Message

Sent immediately after connection with recent visitor history.

{
  "type": "welcome",
  "history": [
    {
      "ts": 1703529600000,
      "city": "New York",
      "country": "US",
      "referrer": "google.com"
    }
  ]
}

2. Hit Event

Sent when a new visitor arrives on your website.

{
  "type": "hit",
  "ts": 1703529600000,
  "ip": "192.168.1.1",
  "city": "London",
  "country": "GB",
  "lat": 51.5074,
  "lon": -0.1278,
  "referrer": "twitter.com",
  "path": "/pricing",
  "ua": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/120.0.0.0"
}

3. Error Message

Sent when an error occurs.

{
  "type": "error",
  "message": "Invalid tracking code"
}

LiveWidget.init(options)

Initialize the LiveWebTraffic widget on your website.

Parameters

Option	Type	Default	Description
trackingCode	String	Required	Your unique tracking code
ws	String	Required	WebSocket server URL
containerId	String	null	Custom container element ID
position	String	'bottom-right'	Widget position: 'bottom-right', 'bottom-left', 'top-right', 'top-left'
theme	String	'light'	Theme: 'light' or 'dark'

Example Usage

// Basic initialization
LiveWidget.init({
  trackingCode: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  ws: 'wss://livewebtraffic.com'
});

// Custom container
LiveWidget.init({
  trackingCode: 'your-code',
  ws: 'wss://livewebtraffic.com',
  containerId: 'my-widget-container'
});

// Dark theme, top-left position
LiveWidget.init({
  trackingCode: 'your-code',
  ws: 'wss://livewebtraffic.com',
  position: 'top-left',
  theme: 'dark'
});