AI Query Coverage

1// AI Query Coverage Measurement Implementation
2 
3interface QueryDefinition {
4  query: string;
5  topicCluster: string;
6  intent: 'informational' | 'commercial' | 'navigational' | 'transactional';
7  funnelStage: 'awareness' | 'consideration' | 'decision' | 'retention';
8  businessValue: 'high' | 'medium' | 'low';
9}
10 
11interface QueryResult {
12  query: QueryDefinition;
13  platform: string;
14  brandAppeared: boolean;
15  competitorsAppeared: string[];
16  timestamp: Date;
17}
18 
19interface CoverageReport {
20  overallCoverage: number;
21  coverageByTopic: Record<string, number>;
22  coverageByIntent: Record<string, number>;
23  coverageByFunnel: Record<string, number>;
24  coverageByPlatform: Record<string, number>;
25  competitiveGaps: CompetitiveGap[];
26  expansionOpportunities: ExpansionOpportunity[];
27}
28 
29interface CompetitiveGap {
30  query: string;
31  topic: string;
32  competitorPresent: string[];
33  businessValue: string;
34}
35 
36interface ExpansionOpportunity {
37  topicCluster: string;
38  currentCoverage: number;
39  queryCount: number;
40  averageBusinessValue: number;
41  priorityScore: number;
42}
43 
44// Calculate comprehensive query coverage
45function calculateQueryCoverage(
46  queryUniverse: QueryDefinition[],
47  results: QueryResult[],
48  competitors: string[]
49): CoverageReport {
50  // Overall coverage
51  const totalQueries = queryUniverse.length;
52  const queriesWithPresence = new Set(
53    results.filter(r => r.brandAppeared).map(r => r.query.query)
54  ).size;
55  const overallCoverage = (queriesWithPresence / totalQueries) * 100;
56  
57  // Coverage by topic
58  const topics = [...new Set(queryUniverse.map(q => q.topicCluster))];
59  const coverageByTopic: Record<string, number> = {};
60  topics.forEach(topic => {
61    const topicQueries = queryUniverse.filter(q => q.topicCluster === topic);
62    const topicResults = results.filter(
63      r => r.query.topicCluster === topic && r.brandAppeared
64    );
65    const uniqueQueriesCovered = new Set(topicResults.map(r => r.query.query)).size;
66    coverageByTopic[topic] = (uniqueQueriesCovered / topicQueries.length) * 100;
67  });
68  
69  // Coverage by intent
70  const intents = ['informational', 'commercial', 'navigational', 'transactional'];
71  const coverageByIntent: Record<string, number> = {};
72  intents.forEach(intent => {
73    const intentQueries = queryUniverse.filter(q => q.intent === intent);
74    const intentResults = results.filter(
75      r => r.query.intent === intent && r.brandAppeared
76    );
77    const uniqueQueriesCovered = new Set(intentResults.map(r => r.query.query)).size;
78    coverageByIntent[intent] = intentQueries.length > 0
79      ? (uniqueQueriesCovered / intentQueries.length) * 100
80      : 0;
81  });
82  
83  // Coverage by funnel stage
84  const stages = ['awareness', 'consideration', 'decision', 'retention'];
85  const coverageByFunnel: Record<string, number> = {};
86  stages.forEach(stage => {
87    const stageQueries = queryUniverse.filter(q => q.funnelStage === stage);
88    const stageResults = results.filter(
89      r => r.query.funnelStage === stage && r.brandAppeared
90    );
91    const uniqueQueriesCovered = new Set(stageResults.map(r => r.query.query)).size;
92    coverageByFunnel[stage] = stageQueries.length > 0
93      ? (uniqueQueriesCovered / stageQueries.length) * 100
94      : 0;
95  });
96  
97  // Coverage by platform
98  const platforms = [...new Set(results.map(r => r.platform))];
99  const coverageByPlatform: Record<string, number> = {};
100  platforms.forEach(platform => {
101    const platformResults = results.filter(r => r.platform === platform);
102    const platformCovered = platformResults.filter(r => r.brandAppeared).length;
103    coverageByPlatform[platform] = (platformCovered / platformResults.length) * 100;
104  });
105  
106  // Identify competitive gaps
107  const competitiveGaps: CompetitiveGap[] = [];
108  queryUniverse.forEach(query => {
109    const queryResults = results.filter(r => r.query.query === query.query);
110    const brandAppeared = queryResults.some(r => r.brandAppeared);
111    const competitorsPresent = new Set<string>();
112    queryResults.forEach(r => {
113      r.competitorsAppeared.forEach(c => competitorsPresent.add(c));
114    });
115    
116    if (!brandAppeared && competitorsPresent.size > 0) {
117      competitiveGaps.push({
118        query: query.query,
119        topic: query.topicCluster,
120        competitorPresent: Array.from(competitorsPresent),
121        businessValue: query.businessValue
122      });
123    }
124  });
125  
126  // Identify expansion opportunities
127  const expansionOpportunities = topics
128    .map(topic => {
129      const topicQueries = queryUniverse.filter(q => q.topicCluster === topic);
130      const coverage = coverageByTopic[topic];
131      const avgValue = calculateAverageBusinessValue(topicQueries);
132      return {
133        topicCluster: topic,
134        currentCoverage: coverage,
135        queryCount: topicQueries.length,
136        averageBusinessValue: avgValue,
137        priorityScore: (100 - coverage) * avgValue * Math.log(topicQueries.length + 1)
138      };
139    })
140    .filter(opp => opp.currentCoverage < 50)
141    .sort((a, b) => b.priorityScore - a.priorityScore);
142  
143  return {
144    overallCoverage,
145    coverageByTopic,
146    coverageByIntent,
147    coverageByFunnel,
148    coverageByPlatform,
149    competitiveGaps,
150    expansionOpportunities
151  };
152}
153 
154function calculateAverageBusinessValue(
155  queries: QueryDefinition[]
156): number {
157  const valueMap = { high: 3, medium: 2, low: 1 };
158  const total = queries.reduce((sum, q) => sum + valueMap[q.businessValue], 0);
159  return total / queries.length;
160}
161 
162// Generate coverage expansion recommendations
163function generateCoverageRecommendations(
164  report: CoverageReport
165): string[] {
166  const recommendations: string[] = [];
167  
168  // Topic-based recommendations
169  report.expansionOpportunities.slice(0, 3).forEach(opp => {
170    recommendations.push(
171      `Priority: Expand coverage in "${opp.topicCluster}" (currently ${opp.currentCoverage.toFixed(1)}% coverage, ${opp.queryCount} queries)`
172    );
173  });
174  
175  // Funnel stage recommendations
176  const lowestFunnelStage = Object.entries(report.coverageByFunnel)
177    .sort(([,a], [,b]) => a - b)[0];
178  if (lowestFunnelStage[1] < 30) {
179    recommendations.push(
180      `Critical gap: ${lowestFunnelStage[0]} stage coverage is only ${lowestFunnelStage[1].toFixed(1)}% - prioritize content for this funnel stage`
181    );
182  }
183  
184  // Competitive gap recommendations
185  const highValueGaps = report.competitiveGaps
186    .filter(g => g.businessValue === 'high');
187  if (highValueGaps.length > 0) {
188    recommendations.push(
189      `${highValueGaps.length} high-value queries where competitors appear but you don't - immediate content needed`
190    );
191  }
192  
193  return recommendations;
194}