API Documentation

Complete REST API for integrating VibeTraffic analytics into your applications. Perfect for freelancers building custom solutions.

Authentication

All API requests require authentication using your API key. Include it in the Authorization header:

HTTP Header

Authorization: Bearer YOUR_API_KEY

Query Parameter (alternative)

?api_key=YOUR_API_KEY

Security Note: Keep your API key secret and never expose it in client-side code. Use server-side implementation for API calls.

API Endpoints

Track Events

POST
/track/YOUR_API_KEY

Request Body

{
  "path": "/pricing",
  "ref": "https://google.com",
  "utm_source": "newsletter",
  "utm_medium": "email",
  "utm_campaign": "launch",
  "ua": "Mozilla/5.0...",
  "ip": "192.168.1.1",
  "screen_w": 1920,
  "screen_h": 1080,
  "lang": "en-US",
  "kind": "pageview",
  "title": "Pricing - vibetraffic.app",
  "search_query": "web analytics"
}

Custom Events

{
  "path": "/signup",
  "kind": "signup",
  "custom_data": {
    "plan": "pro",
    "source": "github"
  }
}

Response

{
  "status": "success",
  "event_id": "evt_1234567890"
}

Get Analytics Stats

GET
/api/stats/YOUR_API_KEY

Query Parameters

start_date

Start date (YYYY-MM-DD)

end_date

End date (YYYY-MM-DD)

limit

Number of results (default: 100)

offset

Pagination offset (default: 0)

Response

{
  "total_views": 15420,
  "total_uniques": 3280,
  "top_pages": [
    {"path": "/", "views": 5230, "uniques": 1200},
    {"path": "/pricing", "views": 2100, "uniques": 890}
  ],
  "top_referrers": [
    {"ref": "https://google.com", "views": 3200},
    {"ref": "https://github.com", "views": 1800}
  ],
  "daily_stats": [
    {"date": "2024-01-01", "views": 450, "uniques": 120},
    {"date": "2024-01-02", "views": 520, "uniques": 140}
  ]
}

Export Data

GET
/api/export/YOUR_API_KEY

Query Parameters

format

Export format: csv, json, xlsx

date_range

Date range: 7d, 30d, 90d, custom

Response

Returns the requested file format for download.

Content-Type: application/csv
Content-Disposition: attachment; filename="analytics-export.csv"

date,path,views,uniques
2024-01-01,/,450,120
2024-01-01,/pricing,180,45

Rate Limits

API Rate Limits

  • Tracking endpoint: 1000 requests/minute
  • Analytics API: 100 requests/minute
  • Export endpoint: 10 requests/hour

Response Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

When rate limits are exceeded, you'll receive a 429 Too Many Requests response.

Code Examples

JavaScript/Node.js

const apiKey = 'YOUR_API_KEY';

// Track page view
fetch(`/track/${apiKey}`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    path: '/pricing',
    kind: 'pageview',
    title: 'Pricing Page'
  })
});

// Get analytics
const response = await fetch(`/api/stats/${apiKey}?start_date=2024-01-01`);
const data = await response.json();
console.log(data.total_views);

Python

import requests
import json

API_KEY = 'YOUR_API_KEY'
BASE_URL = 'https://your-domain.com'

# Track custom event
response = requests.post(
  f'{BASE_URL}/track/{API_KEY}',
  json={
    'path': '/signup',
    'kind': 'signup',
    'custom_data': {'plan': 'pro'}
  }
)

# Get analytics data
response = requests.get(
  f'{BASE_URL}/api/stats/{API_KEY}',
  params={'start_date': '2024-01-01'}
)
data = response.json()
print(f"Total views: {data['total_views']}")

PHP

<?php
$apiKey = 'YOUR_API_KEY';
$baseUrl = 'https://your-domain.com';

// Track event
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "$baseUrl/track/$apiKey");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  'path' => '/contact',
  'kind' => 'form_submit'
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'Content-Type: application/json'
]);
$response = curl_exec($ch);
curl_close($ch);
?>

cURL

# Track page view
curl -X POST https://your-domain.com/track/YOUR_API_KEY \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/pricing",
    "kind": "pageview",
    "title": "Pricing Page"
  }'

# Get analytics
curl "https://your-domain.com/api/stats/YOUR_API_KEY?start_date=2024-01-01" \
  -H "Authorization: Bearer YOUR_API_KEY"

Error Handling

The API returns standard HTTP status codes and includes error details in the response body:

400 Bad Request

Invalid request parameters or malformed JSON

401 Unauthorized

Invalid or missing API key

429 Too Many Requests

Rate limit exceeded

500 Internal Server Error

Server error - try again later

Error Response Format

{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY",
  "message": "The provided API key is not valid or has been revoked"
}