REST API Reference

BuddyPress Stats provides a comprehensive REST API for accessing statistics and analytics data programmatically.

Base URL: https://yoursite.com/wp-json/bp-stats/v1

Authentication

All API endpoints require authentication. Supported methods:

Application Passwords (Recommended)

curl -X GET \
  https://yoursite.com/wp-json/bp-stats/v1/stats \
  -u username:application_password

OAuth 2.0

curl -X GET \
  https://yoursite.com/wp-json/bp-stats/v1/stats \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Nonce (for logged-in users)

fetch('/wp-json/bp-stats/v1/stats', {
  headers: {
    'X-WP-Nonce': wpApiSettings.nonce
  }
});

Core Endpoints

Get Dashboard Statistics

Endpoint: GET /stats

Retrieve overall community statistics.

Parameters:

Parameter Type Description Default
date_from string Start date (YYYY-MM-DD) 30 days ago
date_to string End date (YYYY-MM-DD) Today
metrics array Specific metrics to retrieve All

Example Request:

GET /wp-json/bp-stats/v1/stats?date_from=2025-01-01&date_to=2025-01-31

Example Response:

{
  "success": true,
  "data": {
    "total_users": 1234,
    "active_users": 456,
    "new_users": 23,
    "total_activities": 10234,
    "total_groups": 45,
    "active_groups": 38,
    "engagement_rate": 37.5,
    "growth_rate": 5.2,
    "period": {
      "from": "2025-01-01",
      "to": "2025-01-31"
    }
  }
}

Get User Statistics

Endpoint: GET /users/{user_id}/stats

Retrieve statistics for a specific user.

Parameters:

Parameter Type Description Required
user_id integer User ID Yes
include array Stats to include No
period string Time period (day/week/month/year) No

Example Request:

GET /wp-json/bp-stats/v1/users/123/stats?period=month

Example Response:

{
  "success": true,
  "data": {
    "user_id": 123,
    "username": "johndoe",
    "stats": {
      "total_activities": 234,
      "posts": 45,
      "comments": 89,
      "likes": 100,
      "friends": 67,
      "groups": 12,
      "last_activity": "2025-01-31 14:30:00",
      "engagement_score": 85,
      "activity_trend": [
        {"date": "2025-01-01", "count": 5},
        {"date": "2025-01-02", "count": 8}
      ]
    }
  }
}

Get Group Statistics

Endpoint: GET /groups/{group_id}/stats

Retrieve statistics for a specific group.

Example Response:

{
  "success": true,
  "data": {
    "group_id": 10,
    "name": "Photography Club",
    "stats": {
      "total_members": 156,
      "active_members": 89,
      "total_posts": 1234,
      "posts_this_month": 234,
      "engagement_rate": 57.1,
      "growth_rate": 3.4,
      "top_contributors": [
        {"user_id": 123, "posts": 45},
        {"user_id": 456, "posts": 38}
      ]
    }
  }
}

Analytics Endpoints

Activity Analytics

Endpoint: GET /analytics/activities

Get detailed activity analytics.

Parameters:

Parameter Type Description
type string Activity type filter
user_id integer Filter by user
group_id integer Filter by group
date_from string Start date
date_to string End date
limit integer Number of results
offset integer Pagination offset

Example Response:

{
  "success": true,
  "data": {
    "total": 5678,
    "filtered": 234,
    "activities": [
      {
        "id": 1001,
        "user_id": 123,
        "type": "activity_update",
        "content": "Just joined this amazing community!",
        "date": "2025-01-31 10:30:00",
        "likes": 12,
        "comments": 3
      }
    ],
    "summary": {
      "by_type": {
        "activity_update": 120,
        "activity_comment": 80,
        "joined_group": 34
      },
      "by_hour": {
        "09": 23,
        "10": 45,
        "11": 38
      }
    }
  }
}

Engagement Analytics

Endpoint: GET /analytics/engagement

Get engagement metrics and trends.

Example Response:

{
  "success": true,
  "data": {
    "dau": 234,
    "wau": 567,
    "mau": 890,
    "stickiness": 26.3,
    "retention": {
      "day_1": 85.2,
      "day_7": 65.4,
      "day_30": 45.3
    },
    "engagement_score": 72.5,
    "trends": {
      "daily": [
        {"date": "2025-01-25", "active_users": 210},
        {"date": "2025-01-26", "active_users": 234}
      ]
    }
  }
}

Retention Analytics

Endpoint: GET /analytics/retention

Get user retention cohort data.

Parameters:

Parameter Type Description
cohort_type string daily/weekly/monthly
cohorts integer Number of cohorts

Example Response:

{
  "success": true,
  "data": {
    "cohort_type": "weekly",
    "cohorts": [
      {
        "week": "2025-W01",
        "users": 100,
        "retention": {
          "week_0": 100,
          "week_1": 85,
          "week_2": 72,
          "week_3": 65,
          "week_4": 58
        }
      }
    ]
  }
}

Reports Endpoints

Generate Report

Endpoint: POST /reports/generate

Generate a custom report.

Request Body:

{
  "type": "comprehensive",
  "date_from": "2025-01-01",
  "date_to": "2025-01-31",
  "include": ["users", "activities", "groups", "engagement"],
  "format": "json",
  "email": "admin@example.com"
}

Response:

{
  "success": true,
  "data": {
    "report_id": "rpt_abc123",
    "status": "processing",
    "estimated_time": 30,
    "download_url": null
  }
}

Get Report Status

Endpoint: GET /reports/{report_id}

Check report generation status.

Response:

{
  "success": true,
  "data": {
    "report_id": "rpt_abc123",
    "status": "completed",
    "download_url": "https://yoursite.com/reports/download/rpt_abc123",
    "expires_at": "2025-02-01 00:00:00"
  }
}

List Reports

Endpoint: GET /reports

List all generated reports.

Response:

{
  "success": true,
  "data": {
    "reports": [
      {
        "id": "rpt_abc123",
        "type": "comprehensive",
        "created_at": "2025-01-31 10:00:00",
        "status": "completed",
        "size": "2.4MB"
      }
    ]
  }
}

Search & Filter Endpoints

Search Users by Activity

Endpoint: GET /search/users

Search users based on activity criteria.

Parameters:

Parameter Type Description
min_activities integer Minimum activity count
max_activities integer Maximum activity count
active_since string Active since date
inactive_since string Inactive since date
order_by string Sort field
order string ASC/DESC

Example Response:

{
  "success": true,
  "data": {
    "total": 45,
    "users": [
      {
        "user_id": 123,
        "username": "activeuser",
        "activity_count": 234,
        "last_seen": "2025-01-31 15:00:00",
        "engagement_score": 89
      }
    ]
  }
}

Export Endpoints

Export Data

Endpoint: POST /export

Export statistics data.

Request Body:

{
  "type": "users",
  "format": "csv",
  "filters": {
    "active_since": "2025-01-01",
    "min_activities": 10
  },
  "fields": ["user_id", "username", "email", "activity_count", "last_seen"]
}

Response:

{
  "success": true,
  "data": {
    "export_id": "exp_xyz789",
    "download_url": "https://yoursite.com/exports/exp_xyz789.csv",
    "expires_at": "2025-02-01 00:00:00"
  }
}

Real-time Endpoints

Subscribe to Updates

Endpoint: GET /realtime/subscribe

Subscribe to real-time statistics updates via Server-Sent Events (SSE).

Example:

const eventSource = new EventSource('/wp-json/bp-stats/v1/realtime/subscribe');

eventSource.addEventListener('stats-update', (event) => {
  const data = JSON.parse(event.data);
  console.log('Stats updated:', data);
});

eventSource.addEventListener('activity', (event) => {
  const activity = JSON.parse(event.data);
  console.log('New activity:', activity);
});

Utility Endpoints

Get Plugin Info

Endpoint: GET /info

Get plugin information and capabilities.

Response:

{
  "success": true,
  "data": {
    "version": "1.0.0",
    "capabilities": ["analytics", "reports", "export", "realtime"],
    "limits": {
      "max_export_rows": 10000,
      "max_date_range": 365,
      "rate_limit": "100 requests per minute"
    },
    "supported_formats": ["json", "csv", "xml", "pdf"]
  }
}

Health Check

Endpoint: GET /health

Check API health status.

Response:

{
  "success": true,
  "data": {
    "status": "healthy",
    "database": "connected",
    "cache": "active",
    "queue": "running",
    "last_cron": "2025-01-31 15:00:00"
  }
}

Error Responses

All endpoints return consistent error responses:

{
  "success": false,
  "error": {
    "code": "invalid_parameter",
    "message": "The user_id parameter is required",
    "details": {
      "parameter": "user_id",
      "provided": null,
      "expected": "integer"
    }
  }
}

Common Error Codes

Code Description HTTP Status
unauthorized Authentication required 401
forbidden Insufficient permissions 403
not_found Resource not found 404
invalid_parameter Invalid parameter provided 400
rate_limited Too many requests 429
server_error Internal server error 500

Rate Limiting

API requests are rate-limited to ensure fair usage:

  • Default: 100 requests per minute
  • Authenticated: 1000 requests per minute
  • Premium: Unlimited

Rate limit headers:

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

Code Examples

PHP

$response = wp_remote_get('https://yoursite.com/wp-json/bp-stats/v1/stats', [
    'headers' => [
        'Authorization' => 'Bearer ' . $api_token
    ]
]);

$data = json_decode(wp_remote_retrieve_body($response), true);

JavaScript

async function getStats() {
  const response = await fetch('/wp-json/bp-stats/v1/stats', {
    headers: {
      'X-WP-Nonce': wpApiSettings.nonce
    }
  });
  
  const data = await response.json();
  return data;
}

Python

import requests

response = requests.get(
    'https://yoursite.com/wp-json/bp-stats/v1/stats',
    auth=('username', 'application_password')
)

data = response.json()

cURL

curl -X GET \
  'https://yoursite.com/wp-json/bp-stats/v1/stats?date_from=2025-01-01' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

Webhooks

Configure webhooks to receive real-time notifications:

Available Events

 

  • user.registered – New user registration
  • activity.created – New activity posted
  • group.created – New group created
  • milestone.reached – Community milestone achieved

Webhook Payload

{
  "event": "activity.created",
  "timestamp": "2025-01-31T15:30:00Z",
  "data": {
    "activity_id": 1234,
    "user_id": 567,
    "type": "activity_update",
    "content": "Hello community!"
  }
}
Update on August 28, 2025

BuddyPress Stats