@spec active_visitors(pos_integer(), String.t() | nil) :: non_neg_integer()

Distinct visitors seen in the last minutes — the "right now" number.

@spec browsers(
  filter(),
  keyword()
) :: [map()]

Browser breakdown.

@spec bucket_for(String.t()) :: :hour | :day | :month

The bucket size a period should be charted at.

Short windows get hourly points; a year gets monthly ones, so the chart never tries to draw 365 bars.

@spec channels(
  filter(),
  keyword()
) :: [map()]

Traffic grouped by channel — direct, organic, social, referral, email, paid.

@spec countries(
  filter(),
  keyword()
) :: [map()]

Country breakdown.

Empty unless a geo resolver is configured or the host sits behind a CDN that sets a country header — see PhoenixKitWebAnalytics.Geo.

@spec daily_timeseries(filter()) :: [map()]

Daily page views and visitors, backfilled from rollups where raw events are gone.

Raw events win wherever they exist — a day still present in the events table is always computed from it, and only fully pruned days come from PhoenixKitWebAnalytics.Schemas.DailyStat. Each entry is %{date: Date.t(), pageviews: n, visitors: n, source: :events | :rollup}.

@spec default_period() :: String.t()

The default period when none was requested.

@spec devices(
  filter(),
  keyword()
) :: [map()]

Device class breakdown (desktop / mobile / tablet).

@spec filter(keyword()) :: filter()

Builds a filter.

Options

• :period — one of periods/0's values; an unknown value falls back to the default rather than raising, since it arrives from a query parameter
• :site, :path — optional restrictions
• :now — reference time (tests)

@spec languages(
  filter(),
  keyword()
) :: [map()]

Browser language breakdown.

@spec operating_systems(
  filter(),
  keyword()
) :: [map()]

Operating system breakdown.

@spec overview(filter()) :: map()

Headline totals for the window.

Returns pageviews, visitors, sessions, events, bounce_rate (percent, nil with no sessions), avg_session_seconds (nil with no sessions), and avg_response_ms (nil when nothing recorded a duration).

@spec period_label(String.t()) :: String.t()

The human label for a period value.

@spec period_range(String.t(), DateTime.t() | nil) :: {DateTime.t(), DateTime.t()}

The {from, to} window for a period label, to exclusive.

iex> {from, to} = PhoenixKitWebAnalytics.Reports.period_range("today", ~U[2026-03-04 10:00:00Z])
iex> {DateTime.to_date(from), DateTime.to_date(to)}
{~D[2026-03-04], ~D[2026-03-05]}

@spec periods() :: [{String.t(), String.t()}]

The selectable periods as {value, label} pairs, for the UI.

@spec previous_overview(filter()) :: map() | nil

Totals for the window immediately before this one, for period-over-period comparison. nil for the "all" period, which has no "before".

@spec recent_hits(
  filter(),
  keyword()
) :: [PhoenixKitWebAnalytics.Schemas.Event.t()]

The most recent hits, newest first — the live feed.

Returns whole PhoenixKitWebAnalytics.Schemas.Event structs. Every column is already non-identifying, so there is nothing to redact for display.

Options

• :limit — default 50
• :event_type — "pageview" or "event" to show one kind only

@spec sites(filter()) :: [String.t()]

Hosts that received traffic, for the site selector.

@spec slowest_paths(
  filter(),
  keyword()
) :: [map()]

Slowest paths by average server response time.

This comes free with page-view tracking — the plug already measured the response — and is often the most actionable table here: a page that is both popular and slow shows up in one query. Paths with fewer than three views are excluded, since one cold request would otherwise top the list.

@spec storage_stats() :: %{
  events: non_neg_integer(),
  rollup_days: non_neg_integer(),
  oldest: DateTime.t() | nil
}

Total stored rows and the oldest retained timestamp — shown on the settings page so an operator can see what retention is actually doing.

@spec timeseries(filter(), :hour | :day | :month) :: [map()]

Page views and visitors per time bucket, oldest first.

Empty buckets are filled in with zeros, so a chart doesn't have to reason about gaps. Each entry is %{bucket: DateTime.t(), pageviews: n, visitors: n}.

@spec top_campaigns(
  filter(),
  keyword()
) :: [map()]

Top UTM campaigns.

@spec top_events(
  filter(),
  keyword()
) :: [map()]

Custom events, ranked by occurrence.

@spec top_paths(
  filter(),
  keyword()
) :: [map()]

Most viewed paths.

@spec top_referrers(
  filter(),
  keyword()
) :: [map()]

Top referring sources, excluding internal navigation and direct traffic.

@spec top_utm_sources(
  filter(),
  keyword()
) :: [map()]

Top UTM sources.