# 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 ``` Or via header: ``` X-API-Key: ``` ## Collector Endpoints ### POST /collect/engagement Collect engagement events from clients. **Request Body:** ```json { "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` ```json { "success": true, "eventId": "evt_abc123" } ``` **Example:** ```bash 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:** ```json { "events": [ { "sessionId": "string", "type": "string", "action": "string", "timestamp": "ISO8601", "metadata": {} } ] } ``` **Response:** `202 Accepted` ```json { "success": true, "processed": 10, "failed": 0 } ``` ### POST /collect/device Collect device fingerprint information. **Request Body:** ```json { "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:** ```json { "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:** ```json { "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:** ```json { "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:** ```json { "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:** ```json { "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:** ```json { "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:** ```javascript 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:** ```json { "channel": "active_users", "data": { "count": 156, "byPage": { "/": 45, "/products": 32, "/checkout": 12 } } } ``` ### GET /api/realtime/active Get current active users. **Response:** ```json { "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: ```json { "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 ```