Analytics API

API endpoints for querying and managing analytics data.

Overview

Endpoints

Get Social Metrics

Retrieve aggregated social metrics by date range and platform.

GET /analytics/social-metrics

Query Parameters:

Parameter	Type	Required	Description
startDate	string	No	Start date (YYYY-MM-DD)
endDate	string	No	End date (YYYY-MM-DD)
platform	string	No	Filter by platform

Example Request:

curl "http://localhost:3100/analytics/social-metrics?startDate=2026-01-01&platform=twitter"

Response:

{
  "success": true,
  "data": [
    {
      "metric_date": "2026-02-05",
      "platform": "twitter",
      "impressions": 15420,
      "engagement": 892,
      "reach": 12350,
      "followers": 45230
    },
    {
      "metric_date": "2026-02-04",
      "platform": "twitter",
      "impressions": 14100,
      "engagement": 756,
      "reach": 11800,
      "followers": 45150
    }
  ]
}

---

Get Follower Trends

Get historical follower counts for trend analysis.

GET /analytics/followers

Query Parameters:

Parameter	Type	Required	Description
days	number	No	Number of days back (default: 30)
platform	string	No	Filter by platform

Example Request:

curl "http://localhost:3100/analytics/followers?days=7&platform=instagram"

Response:

{
  "success": true,
  "data": [
    {
      "date": "2026-02-05",
      "platform": "instagram",
      "count": 28450
    },
    {
      "date": "2026-02-04",
      "platform": "instagram",
      "count": 28320
    }
  ]
}

---

Get Top Posts

Get best performing posts by engagement.

GET /analytics/top-posts

Query Parameters:

Parameter	Type	Required	Description
limit	number	No	Number of posts (default: 10)
platform	string	No	Filter by platform
metric	string	No	Sort by: engagement, likes, shares

Example Request:

curl "http://localhost:3100/analytics/top-posts?limit=5&metric=engagement"

Response:

{
  "success": true,
  "data": [
    {
      "post_id": "post-123",
      "platform": "twitter",
      "content": "Check out our latest episode...",
      "likes": 245,
      "comments": 34,
      "shares": 89,
      "total_engagement": 368,
      "engagement_rate": 2.45
    }
  ]
}

---

Trigger Analytics Collection

Manually trigger the analytics collection process.

POST /analytics/collect

Example Request:

curl -X POST http://localhost:3100/analytics/collect

Response:

{
  "success": true,
  "message": "Analytics collection started",
  "platforms": ["twitter", "facebook", "instagram", "linkedin"]
}

---

Ingest Content Metrics

Receive content metrics from external sources (like X Server).

POST /analytics/content-ingest

Request Body:

{
  "contentId": "content-123",
  "platform": "rumble",
  "platformContentId": "v12345",
  "views": 5420,
  "watchHours": 145.5,
  "likes": 234,
  "comments": 45,
  "shares": 12
}

Response:

{
  "success": true,
  "message": "Content metrics ingested",
  "id": 456
}

---

Get Content Metrics

Query content performance data.

GET /analytics/content-metrics

Query Parameters:

Parameter	Type	Required	Description
contentId	string	No	Filter by content ID
platform	string	No	Filter by platform
startDate	string	No	Start date
endDate	string	No	End date

Example Request:

curl "http://localhost:3100/analytics/content-metrics?contentId=content-123"

Response:

{
  "success": true,
  "data": [
    {
      "content_id": "content-123",
      "platform": "rumble",
      "views": 5420,
      "watch_hours": 145.5,
      "likes": 234,
      "comments": 45,
      "collected_at": "2026-02-05T18:00:00.000Z"
    },
    {
      "content_id": "content-123",
      "platform": "youtube",
      "views": 12350,
      "watch_hours": 312.8,
      "likes": 567,
      "comments": 89,
      "collected_at": "2026-02-05T18:00:00.000Z"
    }
  ]
}

---

Data Collection Flow

Collection Implementation

// helpers/cron/collectAnalytics.js
export async function collectAnalytics() {
  const platforms = ['twitter', 'facebook', 'instagram', 'linkedin'];
  
  for (const platform of platforms) {
    // Get platform analytics
    const analytics = await getAyrshareAnalytics(platform);
    
    // Store in PostgreSQL
    await query(
      `INSERT INTO social_metrics 
       (metric_date, platform, impressions, engagement, reach, followers)
       VALUES ($1, $2, $3, $4, $5, $6)
       ON CONFLICT (metric_date, platform) 
       DO UPDATE SET impressions = $3, engagement = $4`,
      [new Date(), platform, analytics.impressions, analytics.engagement, 
       analytics.reach, analytics.followers]
    );
    
    // Store follower count
    await query(
      `INSERT INTO platform_followers (date, platform, count)
       VALUES ($1, $2, $3)
       ON CONFLICT (date, platform) DO UPDATE SET count = $3`,
      [new Date(), platform, analytics.followers]
    );
  }
  
  // Collect post performance
  const posts = await getAyrshareHistory();
  for (const post of posts) {
    await query(
      `INSERT INTO post_performance 
       (post_id, platform, ayrshare_id, content, likes, comments, shares, impressions)
       VALUES ($1, $2, $3, $4, $5, $6, $7, $8)`,
      [post.id, post.platform, post.ayrshareId, post.content,
       post.likes, post.comments, post.shares, post.impressions]
    );
  }
}

Query Helpers

// helpers/postgres/queries.js

export async function getSocialMetrics(startDate, endDate, platform) {
  let sql = `SELECT * FROM social_metrics WHERE 1=1`;
  const params = [];
  
  if (startDate) {
    params.push(startDate);
    sql += ` AND metric_date >= $${params.length}`;
  }
  
  if (endDate) {
    params.push(endDate);
    sql += ` AND metric_date <= $${params.length}`;
  }
  
  if (platform) {
    params.push(platform);
    sql += ` AND platform = $${params.length}`;
  }
  
  sql += ` ORDER BY metric_date DESC`;
  
  return query(sql, params);
}

export async function getTopPosts(limit = 10, platform, metric = 'engagement') {
  const orderBy = {
    engagement: 'likes + comments + shares',
    likes: 'likes',
    shares: 'shares',
  }[metric];
  
  let sql = `
    SELECT *, 
           likes + comments + shares as total_engagement
    FROM post_performance
    WHERE 1=1
  `;
  const params = [];
  
  if (platform) {
    params.push(platform);
    sql += ` AND platform = $${params.length}`;
  }
  
  sql += ` ORDER BY ${orderBy} DESC LIMIT $${params.length + 1}`;
  params.push(limit);
  
  return query(sql, params);
}

Error Handling

All endpoints return consistent error format:

{
  "success": false,
  "error": "Error message",
  "code": "ERROR_CODE"
}

Common Errors:

Code	Description
INVALID_DATE	Invalid date format
DB_ERROR	Database query failed
COLLECTION_FAILED	Analytics collection failed

Related

• PostgreSQL Schema
• Grafana Dashboards
• Social Workflow