Social Media Source Mappings¶
Purpose¶
Source mappings define how canonical Social Media metrics are obtained from specific platform APIs and source objects.
The canonical metric definitions describe the organization's meaning of each metric. This document describes how those metrics are represented by external platforms.
A source field must not be treated as canonical simply because it exists in a platform API.
Mapping Structure¶
Each mapping records:
| Property | Description |
|---|---|
| Platform | External platform providing the source field |
| Source Object | API object containing the field |
| Source Field | Field exposed by the platform |
| Canonical Metric | Organizational metric to which the field maps |
| Mapping Type | Nature of the semantic relationship |
| Confidence | Confidence in the mapping |
| Measurement Type | Snapshot, cumulative, or period aggregate |
| Time Semantics | Point in time, lifetime, or bounded period |
| Historical Availability | Whether historical values can be retrieved |
| Notes | Platform specific limitations or interpretation |
Mapping Types¶
Direct¶
The source field represents substantially the same concept as the canonical metric.
Example:
Instagram
followers_count
↓
social.follower_count
Semantic¶
The source field represents a concept that is sufficiently similar to the canonical metric but uses platform specific terminology or semantics.
Example:
X
retweet_count
↓
social.repost_count
Platform Specific¶
The source field represents a meaningful platform concept but does not map cleanly to a general canonical metric.
Example:
X
tweet_count
↓
social.x.tweet_count
Platform specific fields may remain in the source inventory without becoming canonical organizational metrics.
Current Mappings¶
Audience¶
| Platform | Source Object | Source Field | Canonical Metric | Type | Confidence | Notes |
|---|---|---|---|---|---|---|
| X | Account | public_metrics.followers_count |
social.follower_count |
Direct | High | Account follower count |
| Organization | followerCount |
social.follower_count |
Direct | High | Organization follower count | |
| Account | followers_count |
social.follower_count |
Direct | High | Business or Creator accounts | |
| Page | followers_count |
social.follower_count |
Direct | High | Page follower count | |
| TikTok | Account | follower_count |
social.follower_count |
Direct | High | Account follower count |
| Platform | Source Object | Source Field | Canonical Metric | Type | Confidence | Notes |
|---|---|---|---|---|---|---|
| X | Account | public_metrics.following_count |
social.following_count |
Direct | High | Number of accounts followed |
| Account | follows_count |
social.following_count |
Direct | High | Number of accounts followed | |
| TikTok | Account | following_count |
social.following_count |
Direct | High | Number of accounts followed |
Exposure¶
| Platform | Source Object | Source Field | Canonical Metric | Type | Confidence | Notes |
|---|---|---|---|---|---|---|
| X | Tweet | public_metrics.impression_count |
social.impressions |
Direct | High | Post level impressions |
| OrganizationShare | elements.totalShareStatistics.impressionCount |
social.impressions |
Direct | High | Aggregated over a defined period | |
| Post | impressionCount |
social.impressions |
Direct | High | Post level impressions | |
| MediaInsights | impressions |
social.impressions |
Direct | High | Media level impressions |
Unique Exposure¶
| Platform | Source Object | Source Field | Canonical Metric | Type | Confidence | Notes |
|---|---|---|---|---|---|---|
| MediaInsights | reach |
social.reach |
Direct | High | Unique accounts reached | |
| PostInsights | post_impressions_unique |
social.reach |
Direct | High | Unique people reached |
Video Consumption¶
| Platform | Source Object | Source Field | Canonical Metric | Type | Confidence | Notes |
|---|---|---|---|---|---|---|
| TikTok | Video | view_count |
social.video_view_count |
Semantic | High | Platform specific definition of a video view |
Engagement¶
| Platform | Source Object | Source Field | Canonical Metric | Type | Confidence | Notes |
|---|---|---|---|---|---|---|
| X | Tweet | public_metrics.like_count |
social.like_count |
Direct | High | Post level likes |
| Media | like_count |
social.like_count |
Direct | High | Media level likes | |
| OrganizationShare | elements.totalShareStatistics.likeCount |
social.like_count |
Direct | High | Aggregated organization post likes |
Sharing¶
| Platform | Source Object | Source Field | Canonical Metric | Type | Confidence | Notes |
|---|---|---|---|---|---|---|
| OrganizationShare | elements.totalShareStatistics.shareCount |
social.share_count |
Direct | High | Share actions over a defined period |
Reposting¶
| Platform | Source Object | Source Field | Canonical Metric | Type | Confidence | Notes |
|---|---|---|---|---|---|---|
| X | Tweet | public_metrics.retweet_count |
social.repost_count |
Semantic | Medium | Retweets are treated as reposts in the canonical model |
Page Audience¶
| Platform | Source Object | Source Field | Canonical Metric | Type | Confidence | Notes |
|---|---|---|---|---|---|---|
| Page | fan_count |
social.page_like_count |
Platform Specific | High | Page Likes are distinct from followers |
Platform Specific Fields¶
Not every source field currently maps to a canonical organizational metric.
These fields remain part of the source inventory and may be promoted into the canonical model if a broader organizational use case emerges.
| Platform | Source Object | Source Field | Reason |
|---|---|---|---|
| X | Account | public_metrics.tweet_count |
X specific account metric with no established cross platform equivalent |
Measurement Semantics¶
A direct mapping does not mean that source values can automatically be aggregated together.
Source fields retain their native measurement semantics.
For example:
| Metric | Measurement Type | Time Semantics |
|---|---|---|
| Follower Count | Snapshot | Point in time |
| Following Count | Snapshot | Point in time |
| Impressions | Cumulative | Lifetime or bounded period depending on source |
| Reach | Cumulative | Lifetime or bounded period depending on source |
| Video View Count | Cumulative | Lifetime |
| Like Count | Cumulative | Lifetime |
| Share Count | Period Aggregate | Bounded period |
| Repost Count | Cumulative | Lifetime |
| Page Like Count | Snapshot | Point in time |
This distinction is important when designing the warehouse.
For example, follower counts should normally be stored as periodic snapshots rather than summed. Likewise, reach should not be summed across overlapping content when the underlying values represent unique audiences.
Historical Availability¶
Historical availability varies by platform and metric.
Where the source does not provide historical values, the warehouse must capture periodic snapshots or observations if historical analysis is required.
For example:
Platform API
↓
Current follower count
↓
Daily extraction
↓
Social metric snapshot
↓
Historical audience trend
The absence of API backfill therefore does not necessarily prevent historical reporting. It means history must be accumulated from the point at which collection begins.
Governance¶
Mappings should be reviewed whenever:
- A platform changes its API.
- A source field changes semantics.
- A canonical metric changes definition.
- A new platform is introduced.
- Mapping confidence changes.
- A source field becomes unavailable.
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.