Analytics API

The Analytics API provides endpoints for retrieving and analyzing data related to your application's usage, performance, and user behavior.

Data Retrieval

GET /analytics/summary

Retrieves a high-level summary of key analytics metrics for a specified period.

Parameters:

startDate (string (YYYY-MM-DD)) - The beginning of the date range for the summary.
endDate (string (YYYY-MM-DD)) - The end of the date range for the summary.
granularity (string (optional)) - The time granularity for the data (e.g., 'day', 'week', 'month'). Defaults to 'day'.

Returns:

A JSON object containing summary metrics such as total users, active users, sessions, page views, and event counts.

{
  "period": {
    "startDate": "2023-10-01",
    "endDate": "2023-10-31"
  },
  "metrics": {
    "totalUsers": 15000,
    "activeUsers": 12500,
    "sessions": 35000,
    "pageViews": 150000,
    "events": {
      "eventTypeA": 50000,
      "eventTypeB": 25000
    }
  }
}

Example Request:

curl -X GET \
  https://api.msdn.develop.com/v1/analytics/summary?startDate=2023-10-01&endDate=2023-10-31&granularity=week \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

GET /analytics/events

Retrieves a list of specific events tracked within your application.

Parameters:

eventType (string) - The type of event to retrieve (e.g., 'pageView', 'userLogin', 'itemAddedToCart').
startDate (string (YYYY-MM-DD)) - The beginning of the date range.
endDate (string (YYYY-MM-DD)) - The end of the date range.
userId (string (optional)) - Filter events by a specific user ID.
limit (integer (optional)) - The maximum number of events to return. Defaults to 100.
offset (integer (optional)) - The number of events to skip for pagination. Defaults to 0.

Returns:

A JSON array of event objects, each containing details like timestamp, event type, user ID, and associated data.

[
  {
    "eventId": "evt_abc123",
    "eventType": "pageView",
    "timestamp": "2023-10-25T10:30:00Z",
    "userId": "user_xyz789",
    "properties": {
      "pageUrl": "/products/widgets/123",
      "referrer": "https://www.google.com/"
    }
  },
  {
    "eventId": "evt_def456",
    "eventType": "userLogin",
    "timestamp": "2023-10-25T10:35:15Z",
    "userId": "user_xyz789",
    "properties": {
      "loginMethod": "email"
    }
  }
]

Example Request:

curl -X GET \
  'https://api.msdn.develop.com/v1/analytics/events?eventType=pageView&startDate=2023-10-25&endDate=2023-10-25&userId=user_xyz789&limit=10' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Data Export

POST /analytics/export

Initiates an asynchronous export of analytics data for a specified period and format.

Parameters:

startDate (string (YYYY-MM-DD)) - The beginning of the date range for export.
endDate (string (YYYY-MM-DD)) - The end of the date range for export.
format (string) - The desired export format (e.g., 'csv', 'json', 'parquet').
dataTypes (array of strings) - Specify which data types to include (e.g., ['sessions', 'events', 'userActivity']).

Returns:

A JSON object containing an export job ID and a status. You can poll the `/analytics/export/{jobId}` endpoint to check the status and get the download URL when ready.

{
  "jobId": "exp_jkl789",
  "status": "pending",
  "message": "Export job initiated. Please check status periodically."
}

Example Request:

curl -X POST \
  https://api.msdn.develop.com/v1/analytics/export \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "startDate": "2023-10-01",
    "endDate": "2023-10-31",
    "format": "csv",
    "dataTypes": ["sessions", "pageViews"]
  }'

GET /analytics/export/{jobId}

Retrieves the status and download link for a previously initiated data export job.

Parameters:

jobId (string) - The unique identifier of the export job.

Returns:

A JSON object with the current status of the job and a download URL if the export is complete.

{
  "jobId": "exp_jkl789",
  "status": "completed",
  "downloadUrl": "https://storage.msdn.develop.com/exports/analytics-2023-10.csv?signature=...",
  "expiresAt": "2023-11-15T12:00:00Z"
}

Example Request:

curl -X GET \
  https://api.msdn.develop.com/v1/analytics/export/exp_jkl789 \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'