Web Analytics Source Mappings¶
Purpose¶
Source mappings define how canonical Web Analytics metrics are obtained from the GA4 Data API, across the six properties in scope.
The canonical metric definitions describe the organization's meaning of each metric. This document describes how those metrics are represented by GA4.
A GA4 field must not be treated as canonical simply because it exists in the API response, and — as covered in the field matrix — a GA4 field must not be treated as equivalent to an existing canonical metric simply because the names look alike.
Mapping Structure¶
Each mapping records:
| Property | Description |
|---|---|
| Property | Which of the six GA4 properties the field was observed on (or "All" where uniform) |
| Source Object | GA4 API surface providing the field (standard report, real-time report, cohort report) |
| Source Field | Field exposed by the GA4 Data API |
| Canonical Metric | Organizational metric to which the field maps |
| Mapping Type | Nature of the semantic relationship |
| Confidence | Confidence in the mapping |
| Measurement Type | Cumulative, rate, or derived average |
| Time Semantics | Bounded period unless otherwise noted |
| Historical Availability | Whether historical values can be retrieved |
| Notes | GA4 specific limitations or interpretation |
Mapping Types¶
Direct¶
The source field represents substantially the same concept as the canonical metric.
GA4
sessions
↓
sales.web_sessions
Semantic¶
The source field represents a concept that is sufficiently similar to the canonical metric but needs a transformation, not just a rename, before it matches the canonical definition.
GA4
userEngagementDuration (a sum)
↓
sales.web_avg_engagement_time (an average)
Conditional¶
The mapping is only valid via a different request shape than the one used for the rest of the domain, or only under defined conditions.
GA4 cohort report
cohortActiveUsers / cohortTotalUsers
↓
sales.web_retention_rate
Unresolved¶
The field has been identified as in scope but no GA4 source currently provides it.
Organic search query
↓
(unresolved — requires Search Console, not GA4)
Unresolved fields remain visible here rather than being silently dropped, so the gap stays deliberate rather than accidental.
Current Mappings¶
Acquisition¶
| Property | Source Object | Source Field | Canonical Metric | Type | Confidence | Notes |
|---|---|---|---|---|---|---|
| All | Standard report | activeUsers |
sales.web_users |
Direct | High | GA4's default "Users" figure |
| All | Standard report | newUsers |
sales.web_new_users |
Direct | High | First-time users only |
| All | Standard report | sessions |
sales.web_sessions |
Direct | High | Standard session count |
| All | Standard report | sessionSource / sessionMedium |
dimension on sales.web_sessions |
Direct | High | Session-level traffic source |
| All | Standard report | firstUserSource / firstUserMedium / firstUserDefaultChannelGroup |
dimension on sales.web_users |
Direct | High | Acquisition-time source, distinct from session-level source |
Engagement¶
| Property | Source Object | Source Field | Canonical Metric | Type | Confidence | Notes |
|---|---|---|---|---|---|---|
| All | Standard report | engagementRate |
sales.web_engagement_rate |
Direct | High | Not comparable to sales.engagement_rate (social) — see field matrix |
| All | Standard report | userEngagementDuration |
sales.web_avg_engagement_time |
Semantic | Medium | Divide by sessions to get the per-session average shown in the GA4 UI |
| All | Standard report | screenPageViews |
sales.web_page_views |
Direct | High | Combined page and screen views |
| All | Standard report | pageTitle / pagePath |
dimension on sales.web_page_views |
Direct | High | Page-level breakdown |
| All | Real-time report | audienceName |
dimension on real-time user counts | Conditional | Medium | Not part of the standard lifecycle reports; real-time only, not queryable historically |
Monetization¶
| Property | Source Object | Source Field | Canonical Metric | Type | Confidence | Notes |
|---|---|---|---|---|---|---|
| All | Standard report | conversions |
sales.web_key_event_count |
Direct | High | API field name unchanged; GA4 UI now labels this "Key events" |
| All | Standard report | totalRevenue |
sales.web_revenue |
Direct | High | Expect sparse or zero data for non-ecommerce properties |
| All | Standard report | ecommercePurchases |
context for sales.web_revenue |
Semantic | Medium | A transaction count, not itself a revenue figure |
Retention¶
| Property | Source Object | Source Field | Canonical Metric | Type | Confidence | Notes |
|---|---|---|---|---|---|---|
| All | Cohort report | cohortActiveUsers / cohortTotalUsers |
sales.web_retention_rate |
Conditional | Medium | Requires a cohortSpec request, a different shape from every other mapping in this domain |
Not Yet Sourced¶
Fields identified as conceptually in scope for this domain but not currently obtainable from GA4:
| Concept | Reason unmapped | Likely source if pursued |
|---|---|---|
| Organic search keyword / query performance | GA4 has not exposed search query terms since Google's "(not provided)" change; this data does not exist in the GA4 Data API | Google Search Console, via the Search Console Search Analytics API — a distinct source with its own auth flow, property linking, and field matrix, not an extension of this one |
This is recorded here deliberately rather than mapped to an approximate GA4 field, since no GA4 field represents this concept even approximately.
Measurement Semantics¶
A direct mapping does not mean that source values can automatically be aggregated together.
| Metric | Measurement Type | Time Semantics |
|---|---|---|
| Users | Cumulative (period aggregate) | Bounded period |
| New Users | Cumulative (period aggregate) | Bounded period |
| Sessions | Cumulative (period aggregate) | Bounded period |
| Engagement Rate | Rate | Bounded period, non-additive |
| Average Engagement Time | Derived average | Bounded period, non-additive |
| Page Views | Cumulative (period aggregate) | Bounded period |
| Key Event Count | Cumulative (period aggregate) | Bounded period |
| Revenue | Cumulative (period aggregate) | Bounded period |
| Retention Rate | Rate, cohort-based | Bounded period since acquisition, non-additive |
Rate and derived-average metrics should never be summed across properties or time periods; they must be recomputed from the underlying counts whenever a blended figure is needed across more than one property.
Historical Availability¶
GA4's standard reports can be queried for historical date ranges through the Data API, but this is not unlimited: GA4's underlying event-level data retention is governed by a configurable retention setting (typically 2 or 14 months) at the property level, independent of whether the aggregated report metrics themselves remain queryable for longer. Relying on live queries against GA4 for long-range historical trend reporting is therefore risky in the same way it would be for social platforms with no native history.
GA4 Data API
↓
Current period query
↓
Scheduled extraction
↓
Web analytics metric snapshot
↓
Historical trend (warehouse-side, not GA4-side)
As with Social Media, the absence of unlimited native history does not prevent historical reporting — it means history must be accumulated from the point at which scheduled extraction begins, not assumed to be retrievable retroactively from GA4 itself.
Governance¶
Mappings should be reviewed whenever:
- GA4 changes its API or its Data API field names.
- GA4 changes a metric's underlying calculation (as happened when "conversions" was relabelled "key events" without a field rename).
- A canonical metric changes definition.
- A new property (website or app) is introduced.
- Mapping confidence changes.
- Search Console is linked and keyword data becomes available, at which point it should be evaluated as its own source rather than merged into this one.
The field matrix remains the broader source inventory. This document contains mappings that have been evaluated against the canonical model. The canonical metric definitions remain the authoritative definitions of organizational meaning.