AI Citation Share

1// AI Citation Share Measurement Implementation
2 
3interface Citation {
4  sourceUrl: string;
5  sourceDomain: string;
6  query: string;
7  platform: 'chatgpt' | 'perplexity' | 'google-ai' | 'claude' | 'bing';
8  timestamp: Date;
9  topicCategory: string;
10  citationType: 'explicit' | 'implicit' | 'linked';
11}
12 
13interface CitationShareReport {
14  overallShare: number;
15  competitorShares: Record<string, number>;
16  shareByTopic: Record<string, number>;
17  shareByPlatform: Record<string, number>;
18  trend: {
19    current: number;
20    previous: number;
21    change: number;
22    direction: 'up' | 'down' | 'stable';
23  };
24}
25 
26// Calculate AI Citation Share across multiple dimensions
27function calculateCitationShare(
28  citations: Citation[],
29  yourDomain: string,
30  competitors: string[],
31  period: { start: Date; end: Date }
32): CitationShareReport {
33  const periodCitations = citations.filter(
34    c => c.timestamp >= period.start && c.timestamp <= period.end
35  );
36  
37  const totalCitations = periodCitations.length;
38  const yourCitations = periodCitations.filter(
39    c => c.sourceDomain === yourDomain
40  ).length;
41  
42  // Overall citation share
43  const overallShare = totalCitations > 0 
44    ? (yourCitations / totalCitations) * 100 
45    : 0;
46  
47  // Competitive citation shares
48  const competitorShares: Record<string, number> = {};
49  competitors.forEach(competitor => {
50    const competitorCitations = periodCitations.filter(
51      c => c.sourceDomain === competitor
52    ).length;
53    competitorShares[competitor] = totalCitations > 0
54      ? (competitorCitations / totalCitations) * 100
55      : 0;
56  });
57  
58  // Citation share by topic
59  const topics = [...new Set(periodCitations.map(c => c.topicCategory))];
60  const shareByTopic: Record<string, number> = {};
61  topics.forEach(topic => {
62    const topicCitations = periodCitations.filter(c => c.topicCategory === topic);
63    const yourTopicCitations = topicCitations.filter(
64      c => c.sourceDomain === yourDomain
65    ).length;
66    shareByTopic[topic] = topicCitations.length > 0
67      ? (yourTopicCitations / topicCitations.length) * 100
68      : 0;
69  });
70  
71  // Citation share by platform
72  const platforms = [...new Set(periodCitations.map(c => c.platform))];
73  const shareByPlatform: Record<string, number> = {};
74  platforms.forEach(platform => {
75    const platformCitations = periodCitations.filter(c => c.platform === platform);
76    const yourPlatformCitations = platformCitations.filter(
77      c => c.sourceDomain === yourDomain
78    ).length;
79    shareByPlatform[platform] = platformCitations.length > 0
80      ? (yourPlatformCitations / platformCitations.length) * 100
81      : 0;
82  });
83  
84  // Calculate trend (compare to previous period)
85  const periodLength = period.end.getTime() - period.start.getTime();
86  const previousPeriod = {
87    start: new Date(period.start.getTime() - periodLength),
88    end: period.start
89  };
90  const previousCitations = citations.filter(
91    c => c.timestamp >= previousPeriod.start && c.timestamp < previousPeriod.end
92  );
93  const previousTotal = previousCitations.length;
94  const previousYours = previousCitations.filter(
95    c => c.sourceDomain === yourDomain
96  ).length;
97  const previousShare = previousTotal > 0 
98    ? (previousYours / previousTotal) * 100 
99    : 0;
100  
101  const change = overallShare - previousShare;
102  
103  return {
104    overallShare,
105    competitorShares,
106    shareByTopic,
107    shareByPlatform,
108    trend: {
109      current: overallShare,
110      previous: previousShare,
111      change,
112      direction: change > 1 ? 'up' : change < -1 ? 'down' : 'stable'
113    }
114  };
115}
116 
117// Generate citation share alerts
118function generateCitationAlerts(
119  report: CitationShareReport,
120  thresholds: { minShare: number; maxCompetitorGap: number }
121): string[] {
122  const alerts: string[] = [];
123  
124  if (report.overallShare < thresholds.minShare) {
125    alerts.push(
126      `Citation share (${report.overallShare.toFixed(1)}%) below target (${thresholds.minShare}%)`
127    );
128  }
129  
130  Object.entries(report.competitorShares).forEach(([competitor, share]) => {
131    if (share > report.overallShare + thresholds.maxCompetitorGap) {
132      alerts.push(
133        `${competitor} citation share (${share.toFixed(1)}%) exceeds yours by ${(share - report.overallShare).toFixed(1)}%`
134      );
135    }
136  });
137  
138  if (report.trend.direction === 'down' && Math.abs(report.trend.change) > 5) {
139    alerts.push(
140      `Citation share declining: ${report.trend.change.toFixed(1)}% change from previous period`
141    );
142  }
143  
144  return alerts;
145}