analytics/docs/api-reference.md

API Reference

Complete reference for the Analytics API endpoints.

Base URL

Production: https://analytics.example.com
Development: http://localhost:4001

Authentication

API endpoints use API key authentication:

Authorization: Bearer <api-key>

Or via header:

X-API-Key: <api-key>

Collector Endpoints

POST /collect/engagement

Collect engagement events from clients.

Request Body:

{
  "sessionId": "string (required)",
  "userId": "string (optional)",
  "type": "string (required)",
  "action": "string (required)",
  "timestamp": "ISO8601 string (optional)",
  "metadata": "object (optional)",
  "source": {
    "app": "string",
    "environment": "string"
  }
}

Response: 202 Accepted

{
  "success": true,
  "eventId": "evt_abc123"
}

Example:

curl -X POST https://analytics.example.com/collect/engagement \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "sess_123",
    "type": "navigation",
    "action": "page_view",
    "metadata": {
      "path": "/products",
      "referrer": "https://google.com"
    }
  }'

POST /collect/batch

Collect multiple events in a single request.

Request Body:

{
  "events": [
    {
      "sessionId": "string",
      "type": "string",
      "action": "string",
      "timestamp": "ISO8601",
      "metadata": {}
    }
  ]
}

Response: 202 Accepted

{
  "success": true,
  "processed": 10,
  "failed": 0
}

POST /collect/device

Collect device fingerprint information.

Request Body:

{
  "sessionId": "string (required)",
  "fingerprint": {
    "screenWidth": 1920,
    "screenHeight": 1080,
    "viewportWidth": 1200,
    "viewportHeight": 800,
    "devicePixelRatio": 2,
    "colorDepth": 24,
    "timezone": "America/New_York",
    "language": "en-US",
    "platform": "MacIntel",
    "vendor": "Google Inc.",
    "cookiesEnabled": true,
    "doNotTrack": false
  }
}

Query API Endpoints

GET /api/trends

Get trend data over time.

Query Parameters:

Parameter	Type	Required	Description
metric	string	Yes	Metric to query (pageViews, sessions, users)
startDate	ISO8601	Yes	Start of date range
endDate	ISO8601	Yes	End of date range
granularity	string	No	hour, day, week, month (default: day)
filters	JSON	No	Filter criteria

Response:

{
  "metric": "pageViews",
  "granularity": "day",
  "data": [
    { "date": "2024-01-01", "value": 1523 },
    { "date": "2024-01-02", "value": 1687 },
    { "date": "2024-01-03", "value": 1456 }
  ],
  "total": 4666,
  "change": 12.5
}

GET /api/funnels

Get funnel conversion data.

Query Parameters:

Parameter	Type	Required	Description
funnelId	string	Yes	Funnel identifier
startDate	ISO8601	Yes	Start of date range
endDate	ISO8601	Yes	End of date range
steps	JSON array	No	Custom funnel steps

Response:

{
  "funnelId": "checkout",
  "steps": [
    { "name": "Cart View", "count": 10000, "rate": 100 },
    { "name": "Begin Checkout", "count": 6500, "rate": 65 },
    { "name": "Add Payment", "count": 4200, "rate": 42 },
    { "name": "Purchase", "count": 3100, "rate": 31 }
  ],
  "overallConversion": 31,
  "dropoffs": [
    { "from": "Cart View", "to": "Begin Checkout", "lost": 3500, "rate": 35 },
    { "from": "Begin Checkout", "to": "Add Payment", "lost": 2300, "rate": 35.4 },
    { "from": "Add Payment", "to": "Purchase", "lost": 1100, "rate": 26.2 }
  ]
}

GET /api/cohorts

Get cohort retention data.

Query Parameters:

Parameter	Type	Required	Description
cohortType	string	Yes	signup_date, first_purchase, etc.
startDate	ISO8601	Yes	Start of cohort range
endDate	ISO8601	Yes	End of cohort range
periods	number	No	Number of retention periods (default: 12)

Response:

{
  "cohortType": "signup_date",
  "cohorts": [
    {
      "date": "2024-01",
      "size": 1000,
      "retention": [100, 45, 38, 32, 28, 25]
    },
    {
      "date": "2024-02",
      "size": 1200,
      "retention": [100, 48, 41, 35, 30]
    }
  ]
}

GET /api/segments

Get data segmented by dimension.

Query Parameters:

Parameter	Type	Required	Description
dimension	string	Yes	Segmentation dimension
metric	string	Yes	Metric to aggregate
startDate	ISO8601	Yes	Start of date range
endDate	ISO8601	Yes	End of date range
limit	number	No	Max segments (default: 10)

Available Dimensions:

• country - Geographic country
• device - Device type (mobile, tablet, desktop)
• browser - Browser name
• os - Operating system
• source - Traffic source
• medium - Traffic medium
• campaign - Campaign name

Response:

{
  "dimension": "device",
  "metric": "sessions",
  "segments": [
    { "name": "desktop", "value": 45000, "percentage": 56.2 },
    { "name": "mobile", "value": 30000, "percentage": 37.5 },
    { "name": "tablet", "value": 5000, "percentage": 6.3 }
  ],
  "total": 80000
}

GET /api/acquisition

Get traffic acquisition data.

Query Parameters:

Parameter	Type	Required	Description
startDate	ISO8601	Yes	Start of date range
endDate	ISO8601	Yes	End of date range
groupBy	string	No	source, medium, campaign

Response:

{
  "channels": [
    {
      "channel": "Organic Search",
      "sessions": 25000,
      "users": 20000,
      "newUsers": 15000,
      "bounceRate": 45.2,
      "avgSessionDuration": 180,
      "conversions": 500,
      "conversionRate": 2.0
    },
    {
      "channel": "Direct",
      "sessions": 18000,
      "users": 12000,
      "newUsers": 3000,
      "bounceRate": 35.8,
      "avgSessionDuration": 240,
      "conversions": 800,
      "conversionRate": 4.4
    }
  ]
}

GET /api/engagement

Get engagement metrics.

Query Parameters:

Parameter	Type	Required	Description
startDate	ISO8601	Yes	Start of date range
endDate	ISO8601	Yes	End of date range

Response:

{
  "metrics": {
    "avgSessionDuration": 185,
    "avgPageViewsPerSession": 3.2,
    "bounceRate": 42.5,
    "avgScrollDepth": 65,
    "engagementRate": 57.5
  },
  "topPages": [
    { "path": "/", "views": 50000, "avgTime": 45 },
    { "path": "/products", "views": 35000, "avgTime": 120 },
    { "path": "/pricing", "views": 28000, "avgTime": 90 }
  ],
  "topEvents": [
    { "action": "add_to_cart", "count": 8500 },
    { "action": "signup_click", "count": 6200 },
    { "action": "video_play", "count": 4800 }
  ]
}

Realtime Endpoints

WebSocket /realtime

Connect to receive real-time analytics updates.

Connection:

const ws = new WebSocket('wss://analytics.example.com/realtime');

ws.onopen = () => {
  // Subscribe to channels
  ws.send(JSON.stringify({
    type: 'subscribe',
    channels: ['active_users', 'page_views', 'events']
  }));
};

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

Messages:

{
  "channel": "active_users",
  "data": {
    "count": 156,
    "byPage": {
      "/": 45,
      "/products": 32,
      "/checkout": 12
    }
  }
}

GET /api/realtime/active

Get current active users.

Response:

{
  "activeUsers": 156,
  "activeSessions": 142,
  "byCountry": [
    { "country": "US", "count": 65 },
    { "country": "UK", "count": 23 },
    { "country": "DE", "count": 18 }
  ],
  "byPage": [
    { "path": "/", "count": 45 },
    { "path": "/products", "count": 32 }
  ],
  "recentEvents": [
    { "action": "purchase", "timestamp": "2024-01-15T10:30:00Z" },
    { "action": "signup", "timestamp": "2024-01-15T10:29:45Z" }
  ]
}

Error Responses

All endpoints return consistent error responses:

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Invalid date format for startDate",
    "details": {
      "parameter": "startDate",
      "provided": "2024-13-01",
      "expected": "ISO8601 date string"
    }
  }
}

Error Codes:

Code	HTTP Status	Description
INVALID_PARAMETER	400	Invalid request parameter
MISSING_PARAMETER	400	Required parameter missing
UNAUTHORIZED	401	Invalid or missing API key
FORBIDDEN	403	Insufficient permissions
NOT_FOUND	404	Resource not found
RATE_LIMITED	429	Too many requests
INTERNAL_ERROR	500	Server error

Rate Limits

Endpoint Type	Limit
Collector	1000 req/min per session
Query API	100 req/min per API key
Realtime	10 connections per API key

Rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705312800