Analytics Reporting API

��� Generate Report

Endpoint: GET /v1/integrations/google/analytics/report/:id

Path Parameters:

• id (required) - View ID (v3) or Property ID (v4)

��� Query Parameters

Common Parameters

• start (required) - Start date (YYYY-MM-DD)
• end (required) - End date (YYYY-MM-DD)
• dimensions (optional) - Comma-separated dimensions
• metrics (optional) - Comma-separated metrics
• sort (optional) - Sort field
• order (optional) - "asc" or "desc"
• limit (optional) - Results per page (default: 20)
• page (optional) - Page number (default: 1)

v3-Specific Parameters

• daterange (optional) - Date range dimension (e.g., "date", "month")

��� Examples

Basic Report (v3)

Request:

GET /v1/integrations/google/analytics/report/219224050?start=2025-09-01&end=2025-10-10&metrics=users,sessions&dimensions=country&sort=users&order=desc&limit=10&page=1
Authorization: Bearer {jwt_token}

Response:

{
  "success": true,
  "message": "SUCCESS",
  "data": {
    "columnHeaders": ["ga:country", "ga:users", "ga:sessions"],
    "rows": [
      ["United States", "1234", "2345"],
      ["Canada", "567", "789"],
      ["United Kingdom", "234", "345"]
    ]
  },
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 50
  }
}

Organic Search Report (v4)

Request:

GET /v1/integrations/google/analytics/report/12345678?start=2025-09-01&end=2025-10-10&metrics=activeUsers,sessions&dimensions=organicSearches&limit=20&page=1
Authorization: Bearer {jwt_token}

Response:

{
  "success": true,
  "message": "SUCCESS",
  "data": {
    "columnHeaders": ["defaultChannelGrouping", "activeUsers", "sessions"],
    "rows": [["Organic Search", "5678", "8901"]]
  },
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1
  }
}

��� Available Dimensions & Metrics

Common Dimensions

Geographic:

• country, city, region, continent

Technology:

• browser, operatingSystem, deviceCategory, screenResolution

Traffic Sources:

• source, medium, campaign, keyword

Content:

• pagePath, pageTitle, landingPagePath, exitPagePath

Time:

• date, month, year, hour, dayOfWeek

Common Metrics

Users:

• users, activeUsers, newUsers, 1dayUsers, 7dayUsers, 28dayUsers

Sessions:

• sessions, bounceRate, sessionDuration, sessionsPerUser

Pageviews:

• pageviews, uniquePageviews, avgTimeOnPage, entrances, exits

Conversions:

• goalCompletionsAll, goalConversionRateAll, transactionRevenue

��� Provider Methods

generateReport()

Purpose: Generate GA4 analytics report

API: POST https://analyticsdata.googleapis.com/v1beta/properties/{propertyId}:runReport

Request Body:

{
  dateRanges: [{
    startDate: "2025-09-01",
    endDate: "2025-10-10"
  }],
  dimensions: [{
    name: "country"
  }],
  metrics: [{
    name: "activeUsers"
  }],
  orderBys: [{
    dimension: {
      orderType: "NUMERIC",
      dimensionName: "activeUsers"
    },
    desc: true
  }],
  dimensionFilter: {
    filter: {
      fieldName: "defaultChannelGrouping",
      stringFilter: {
        matchType: "EXACT",
        value: "Organic Search"
      }
    }
  },
  keepEmptyRows: true,
  returnPropertyQuota: true
}

Returns: Report data with dimensions and metrics

��� Report Types

Traffic Report

Dimensions: source, medium, campaign
Metrics: users, sessions, bounceRate

GET /report/219224050?start=2025-09-01&end=2025-10-10&dimensions=source,medium&metrics=users,sessions&sort=sessions&order=desc

Geographic Report

Dimensions: country, city
Metrics: users, sessions, pageviews

GET /report/219224050?start=2025-09-01&end=2025-10-10&dimensions=country,city&metrics=users,pageviews&limit=50

Device Report

Dimensions: deviceCategory, browser
Metrics: users, sessions, avgSessionDuration

GET /report/219224050?start=2025-09-01&end=2025-10-10&dimensions=deviceCategory,browser&metrics=users,sessions

Content Report

Dimensions: pagePath, pageTitle
Metrics: pageviews, uniquePageviews, avgTimeOnPage

GET /report/219224050?start=2025-09-01&end=2025-10-10&dimensions=pagePath&metrics=pageviews,avgTimeOnPage&sort=pageviews&order=desc

⚡ Performance

API Call Latency

• Token validity check: < 1ms
• Token refresh (if needed): 200-500ms
• Report generation: 500-2000ms (depends on complexity)

Rate Limiting

• Google Analytics API: 10 requests/second per project
• Consider implementing request queuing for high-volume usage

Optimization Tips

1. Limit Date Ranges: Shorter ranges = faster responses
2. Reduce Dimensions: Fewer dimensions = less processing
3. Use Sampling: For large datasets, enable sampling
4. Cache Results: Cache frequently requested reports
5. Batch Requests: Combine multiple metrics in single call

⚠️ Important Notes

• ��� Version Support: Both v3 and v4 APIs supported
• ��� Auto Token Refresh: Tokens refreshed before each request
• ��� Pagination: v3 uses page/limit, v4 uses pageToken
• ��� Flexible Metrics: Custom dimensions and metrics supported
• ⚡ Performance: Most reports generated in < 2 seconds
• ��� Complex Queries: Support for filters, segments, and custom dimensions

��� External Resources

• v3 Dimensions & Metrics
• v4 API Schema
• Core Reporting API v3
• Data API v4
• Query Explorer

��� Related Documentation

• Authentication
• Accounts & Properties