Analytics Endpoints

Overview

These endpoints provide access to your website analytics data, including statistics, metrics, and time-series data for building custom dashboards and reports.

Analytics Endpoints

GET /api/websites/:websiteId

Returns basic website statistics.

Parameters:

websiteId (path): ID of the website
startDate (query, optional): Starting date for data range (YYYY-MM-DD)
endDate (query, optional): Ending date for data range (YYYY-MM-DD)

Response:

{
  "sessions": 12450,
  "events": 45320,   // Total of all events (including pageviews)
  "pageviews": 28740  // Only page_view events
}

GET /api/websites/:websiteId/stats

Returns statistics with current and previous period comparisons.

Parameters:

websiteId (path): ID of the website
startAt, endAt (query, optional): Timestamps for date range
Optional filters (query): url, referrer, browser, os, device, country

Response:

{
  "pageviews": { 
    "value": 8500, 
    "prev": 7900 
  },
  "visitors": { 
    "value": 5000, 
    "prev": 4700 
  },
  "visits": { 
    "value": 5500,
    "prev": 5100 
  },
  "bounces": { 
    "value": 2338, 
    "prev": 2193 
  },
  "totaltime": { 
    "value": 687500, 
    "prev": 612000 
  }
}

GET /api/websites/:websiteId/chart-data

Returns time-series data for charts and graphs.

Parameters:

websiteId (path): ID of the website
timeframe (query, optional): Predefined timeframes (‘today’, ‘yesterday’, ‘last7days’, ‘last30days’, ‘custom’)
startDate, endDate (query, optional): Date range for custom timeframe
interval (query, optional): Time granularity (‘hourly’, ‘daily’, ‘auto’)
metric (query, optional): ‘pageviews’, ‘visitors’, ‘sessions’, ‘events’
event (query, optional): Filter by specific event name

Response:

{
  "timeseries": [
    {
      "date": "2023-05-01T00:00:00",
      "pageviews": 500,
      "sessions": 350,
      "visitors": 350,
      "avg_duration": 120,
      "bounce_rate": 42.5
    }
  ],
  "totals": {
    "pageviews": 8500,
    "visitors": 5000,
    "sessions": 5500,
    "avg_duration": 125,
    "bounce_rate": 42.5
  },
  "interval": "daily"
}

GET /api/websites/:websiteId/metrics

Returns comprehensive metrics for analytics dashboards.

Parameters:

websiteId (path): ID of the website
timeframe (query, optional): Predefined timeframe
startDate, endDate (query, optional): Custom date range
interval (query, optional): Time interval for grouping

Response:

{
  "timeseries": [
    {
      "date": "2023-05-01",
      "pageviews": 8500,
      "visitors": 5000,
      "sessions": 5500,
      "bounce_rate": 42.5,
      "avg_duration": 125
    }
  ],
  "countries": [
    {
      "country": "United States",
      "visitors": 450,
      "percentage": 50.6
    }
  ],
  "browsers": [
    {
      "browser": "Chrome",
      "visitors": 320,
      "percentage": 36.0
    }
  ],
  "os": [
    {
      "os": "Windows",
      "visitors": 280,
      "percentage": 31.5
    }
  ],
  "devices": [
    {
      "device": "Desktop",
      "visitors": 600,
      "percentage": 67.4
    }
  ],
  "pages": [
    {
      "path": "/products",
      "title": "Products",
      "pageviews": 450,
      "visitors": 320,
      "percentage": 15.2
    }
  ],
  "referrers": [
    {
      "domain": "google.com",
      "visitors": 180,
      "percentage": 20.2
    }
  ],
  "totals": {
    "pageviews": 12500,        // Count of page_view events only
    "visitors": 8900,          // Unique visitors (distinct session_id)
    "sessions": 9200,          // Total sessions
    "bounce_rate": 45.2,       // Percentage of single-page sessions
    "avg_duration": 180.5,     // Average session duration in seconds
    "events": 25000            // Total count of all events
  }
}

GET /api/websites/:websiteId/pageviews

Returns pageview data with optional grouping.

Parameters:

websiteId (path): ID of the website
startDate, endDate (query, optional): Date range
limit, offset (query, optional): Pagination parameters
url (query, optional): Filter by page URL
groupBy (query, optional): Group results by: ‘url’, ‘referrer’, or ‘time’

Response (when groupBy=url):

{
  "pageviews": [
    {
      "path": "/products",
      "title": "Products Page",
      "views": 2500,
      "unique_views": 1800,
      "first_view": "2023-05-01T00:00:00Z",
      "last_view": "2023-05-15T23:59:59Z",
      "avg_time_on_page": 65.2
    }
  ],
  "pagination": {
    "total": 120,
    "limit": 100,
    "offset": 0,
    "hasMore": true
  }
}

Usage Examples

Get Basic Website Statistics

GET /api/websites/abc123/stats?startAt=1683072000000&endAt=1685750399000

Get Time-Series Data for Charts

GET /api/websites/abc123/chart-data?timeframe=last7days&interval=daily&metric=pageviews

Get Comprehensive Dashboard Metrics

GET /api/websites/abc123/metrics?timeframe=last30days

Get Page Performance Data

GET /api/websites/abc123/pageviews?groupBy=url&limit=50

Filtering Options

Most analytics endpoints support filtering by:

Time Range: startDate, endDate, timeframe
Page: url parameter
Traffic Source: referrer parameter
Technology: browser, os, device parameters
Geography: country parameter

Time Intervals

When requesting time-series data, you can specify intervals:

minute: Minute-by-minute data (for real-time)
hour: Hourly aggregation
day: Daily aggregation
week: Weekly aggregation
month: Monthly aggregation
auto: Automatically choose based on date range

Predefined Timeframes

Use these convenient timeframes instead of custom date ranges:

today: Current day
yesterday: Previous day
last7days: Last 7 days
last30days: Last 30 days
custom: Use with startDate and endDate

Getting Started

Setup

Analytics

Server-side Hosts

Connections

ETL/Data Governance

FAQ

Changelog

Analytics Endpoints

Overview