453 lines
9 KiB
Markdown
453 lines
9 KiB
Markdown
# 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:**
|
|
|
|
```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
|
|
```
|