get_search_terms
Analyzes site search keywords from Google Analytics 4 data to identify what users search for within your website, providing insights into user intent and content gaps.
Instructions
サイト内検索キーワードを分析します。GA4でサイト内検索が設定されている場合のみ有効です。
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| propertyId | No | GA4プロパティID | |
| period | Yes | 集計期間 | |
| limit | No | 取得件数（デフォルト: 20） |
Implementation Reference
- The main handler function that fetches and processes GA4 report data for site search terms, filtering by 'view_search_results' event and calculating metrics like search exit rate.export async function getSearchTerms( input: GetSearchTermsInput ): Promise<GetSearchTermsOutput> { const propertyId = getPropertyId(input.propertyId); const property = formatPropertyPath(propertyId); const dateRange = periodToDateRange(input.period); const limit = input.limit || 20; // サイト内検索キーワードを取得 // GA4では searchTerm ディメンションを使用 const response = await executeReport({ property, dateRanges: [dateRange], dimensions: [{ name: "searchTerm" }], metrics: [ { name: "eventCount" }, { name: "totalUsers" }, { name: "screenPageViews" }, ], orderBys: [{ metric: { metricName: "eventCount" }, desc: true }], limit, // view_search_results イベントでフィルター dimensionFilter: { filter: { fieldName: "eventName", stringFilter: { matchType: "EXACT", value: "view_search_results", }, }, }, }); // 合計イベント数を取得（検索離脱率計算用） const totalSearches = response.totals?.[0]?.metricValues?.[0]?.value ? parseFloat(response.totals[0].metricValues[0].value) : 0; const searchTerms: SearchTerm[] = []; for (const row of response.rows || []) { const term = row.dimensionValues?.[0]?.value || ""; const metricValues = row.metricValues || []; const getValue = (index: number): number => { const value = metricValues[index]?.value; return value ? parseFloat(value) : 0; }; const searchCount = Math.round(getValue(0)); const uniqueSearches = Math.round(getValue(1)); const resultsPageviews = Math.round(getValue(2)); // 検索離脱率: 結果ページを見た後に離脱した割合（概算） // 正確な計算には追加のイベント分析が必要 const searchExitRate = calculatePercentage( searchCount - resultsPageviews, searchCount ); searchTerms.push({ term, searchCount, uniqueSearches, resultsPageviews, searchExitRate, }); } return { searchTerms }; }
- src/types.ts:409-425 (schema)TypeScript interfaces defining the input parameters (period, limit), SearchTerm structure, and output for the get_search_terms tool.// get_search_terms export interface GetSearchTermsInput extends PropertyId { period: ShortPeriod; limit?: number; } export interface SearchTerm { term: string; searchCount: number; uniqueSearches: number; resultsPageviews: number; searchExitRate: string; } export interface GetSearchTermsOutput { searchTerms: SearchTerm[]; }
- src/server.ts:540-560 (registration)MCP tool registration entry in the tools array, including name, description, and input schema for get_search_terms.{ name: "get_search_terms", description: "サイト内検索キーワードを分析します。GA4でサイト内検索が設定されている場合のみ有効です。", inputSchema: { type: "object" as const, properties: { propertyId: { type: "string", description: "GA4プロパティID" }, period: { type: "string", enum: ["7days", "28days", "30days"], description: "集計期間", }, limit: { type: "number", description: "取得件数（デフォルト: 20）", }, }, required: ["period"], }, },
- src/server.ts:744-749 (registration)Switch case in handleToolCall that dispatches to the getSearchTerms handler function.case "get_search_terms": return await getSearchTerms({ propertyId: args.propertyId as string | undefined, period: args.period as "7days" | "28days" | "30days", limit: args.limit as number | undefined, });
- src/tools/analytics/index.ts:15-15 (helper)Re-export of the getSearchTerms handler from its module for convenient import in server.ts.export { getSearchTerms } from "./getSearchTerms.js";