Analytics API

Complete API reference for analytics, reports, and business intelligence.

Base Endpoint

/api/v1/analytics

Customer Analytics

Get Customer Activity

Get customer activity metrics.

GET /api/v1/analytics/customers/activity

Query Parameters

Parameter	Type	Description
date_from	string	Start date (ISO 8601)
date_to	string	End date (ISO 8601)
group_by	string	Group by (day, week, month)
segment_id	string	Filter by segment

Example Response

{
  "data": {
    "period": {
      "from": "2024-01-01",
      "to": "2024-01-31"
    },
    "metrics": {
      "active_users": 12500,
      "new_registrations": 850,
      "check_ins": 45200,
      "purchases": 12300
    },
    "by_date": [
      {
        "date": "2024-01-01",
        "active_users": 450,
        "new_registrations": 25,
        "check_ins": 1200,
        "purchases": 380
      }
    ]
  }
}

Get Customer Segments Distribution

Get distribution of customers across segments.

GET /api/v1/analytics/customers/segments

Example Response

{
  "data": {
    "total_customers": 50000,
    "by_segment": [
      {
        "segment_id": "seg_123",
        "segment_name": "Gold Members",
        "count": 5000,
        "percentage": 10
      },
      {
        "segment_id": "seg_456",
        "segment_name": "High Value",
        "count": 2500,
        "percentage": 5
      }
    ]
  }
}

Sales Analytics

Get Sales Summary

Get sales summary metrics.

GET /api/v1/analytics/sales/summary

Query Parameters

Parameter	Type	Description
date_from	string	Start date
date_to	string	End date
store_id	string	Filter by store
category	string	Filter by category

Example Response

{
  "data": {
    "period": {
      "from": "2024-01-01",
      "to": "2024-01-31"
    },
    "metrics": {
      "total_sales": 2500000,
      "transaction_count": 12300,
      "average_basket_size": 203.25,
      "growth_rate": 0.15
    },
    "by_store": [
      {
        "store_id": "store_123",
        "store_name": "Store A",
        "sales": 500000,
        "transactions": 2500
      }
    ],
    "by_category": [
      {
        "category": "fashion",
        "sales": 1000000,
        "percentage": 40
      }
    ]
  }
}

Get Sales Trends

Get sales trends over time.

GET /api/v1/analytics/sales/trends

Query Parameters

Parameter	Type	Description
date_from	string	Start date
date_to	string	End date
group_by	string	Group by (day, week, month)

Loyalty Analytics

Get Points Analytics

Get points earned and redeemed analytics.

GET /api/v1/analytics/loyalty/points

Example Response

{
  "data": {
    "period": {
      "from": "2024-01-01",
      "to": "2024-01-31"
    },
    "metrics": {
      "points_earned": 500000,
      "points_redeemed": 300000,
      "points_expired": 5000,
      "active_balance": 195000
    },
    "by_tier": [
      {
        "tier": "gold",
        "points_earned": 200000,
        "points_redeemed": 120000
      }
    ]
  }
}

Get Reward Redemption Analytics

Get reward redemption metrics.

GET /api/v1/analytics/loyalty/rewards

Example Response

{
  "data": {
    "period": {
      "from": "2024-01-01",
      "to": "2024-01-31"
    },
    "metrics": {
      "rewards_claimed": 5000,
      "rewards_redeemed": 4500,
      "redemption_rate": 0.90,
      "total_value": 50000
    },
    "top_rewards": [
      {
        "reward_id": "rew_123",
        "reward_name": "10% Discount",
        "claims": 2000,
        "redemptions": 1800
      }
    ]
  }
}

Campaign Analytics

Get Campaign Performance

Get campaign performance metrics.

GET /api/v1/analytics/campaigns/{campaign_id}

Example Response

{
  "data": {
    "campaign_id": "camp_123",
    "campaign_name": "Summer Sale 2024",
    "metrics": {
      "reach": 50000,
      "participants": 12500,
      "conversions": 4380,
      "conversion_rate": 0.0876,
      "revenue": 1250000,
      "roi": 2.5
    },
    "by_segment": [
      {
        "segment_id": "seg_123",
        "segment_name": "Gold Members",
        "participants": 5000,
        "conversions": 2000,
        "conversion_rate": 0.40
      }
    ]
  }
}

Real-Time Dashboard

Get Dashboard Metrics

Get real-time dashboard metrics.

GET /api/v1/analytics/dashboard

Query Parameters

Parameter	Type	Description
time_range	string	Time range (today, 7d, 30d)

Example Response

{
  "data": {
    "customer_activity": {
      "active_users_now": 450,
      "active_users_today": 2500,
      "new_registrations_today": 25
    },
    "sales": {
      "sales_today": 50000,
      "transactions_today": 250,
      "average_basket_size": 200
    },
    "loyalty": {
      "points_earned_today": 5000,
      "points_redeemed_today": 3000,
      "rewards_claimed_today": 50
    },
    "campaigns": {
      "active_campaigns": 5,
      "participants_today": 150,
      "conversions_today": 45
    }
  }
}

Export Reports

Generate Report

Generate and download a report.

POST /api/v1/analytics/reports/generate

Request Body

{
  "type": "customer_activity",
  "format": "csv",
  "date_from": "2024-01-01",
  "date_to": "2024-01-31",
  "filters": {
    "segment_id": "seg_123"
  }
}

Example Response

{
  "data": {
    "report_id": "rpt_123",
    "status": "processing",
    "download_url": null,
    "estimated_completion": "2024-01-20T15:05:00Z"
  }
}

Get Report Status

Check report generation status.

GET /api/v1/analytics/reports/{report_id}

Example Response

{
  "data": {
    "report_id": "rpt_123",
    "status": "completed",
    "download_url": "https://...",
    "expires_at": "2024-01-27T15:00:00Z"
  }
}