get_hourly_traffic
Analyze hourly traffic patterns from Google Analytics 4 data to optimize content publication and campaign timing based on user activity trends.
Instructions
時間帯別のアクセス状況を分析します。投稿やキャンペーンのタイミング最適化に活用できます。
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| propertyId | No | GA4プロパティID | |
| period | Yes | 集計期間 |
Implementation Reference
- Core handler function that executes the get_hourly_traffic tool logic: fetches GA4 hourly report, calculates daily averages for users and pageviews, determines peak and quiet hours based on thresholds.export async function getHourlyTraffic( input: GetHourlyTrafficInput ): Promise<GetHourlyTrafficOutput> { const propertyId = getPropertyId(input.propertyId); const property = formatPropertyPath(propertyId); const dateRange = periodToDateRange(input.period); const dayCount = getDayCount(dateRange); const response = await executeReport({ property, dateRanges: [dateRange], dimensions: [{ name: "hour" }], metrics: [{ name: "totalUsers" }, { name: "screenPageViews" }], orderBys: [{ dimension: { dimensionName: "hour" }, desc: false }], limit: 24, }); // 時間ごとのデータを初期化（0-23時） const hourlyMap = new Map<number, { users: number; pageViews: number }>(); for (let i = 0; i < 24; i++) { hourlyMap.set(i, { users: 0, pageViews: 0 }); } // レスポンスからデータを収集 for (const row of response.rows || []) { const hour = parseInt(row.dimensionValues?.[0]?.value || "0", 10); const users = row.metricValues?.[0]?.value ? parseFloat(row.metricValues[0].value) : 0; const pageViews = row.metricValues?.[1]?.value ? parseFloat(row.metricValues[1].value) : 0; hourlyMap.set(hour, { users, pageViews }); } // 平均を計算してHourlyData配列を作成 const hourlyData: HourlyData[] = []; let maxUsers = 0; let minUsers = Infinity; for (let hour = 0; hour < 24; hour++) { const data = hourlyMap.get(hour)!; const avgUsers = roundToDecimal(data.users / dayCount); const avgPageViews = roundToDecimal(data.pageViews / dayCount); if (avgUsers > maxUsers) maxUsers = avgUsers; if (avgUsers < minUsers) minUsers = avgUsers; hourlyData.push({ hour, avgUsers, avgPageViews, peakIndicator: false, // 後で設定 }); } // ピーク判定の閾値（平均値の1.5倍以上） const avgAllHours = hourlyData.reduce((sum, h) => sum + h.avgUsers, 0) / 24; const peakThreshold = avgAllHours * 1.5; const quietThreshold = avgAllHours * 0.5; // ピーク時間帯と閑散時間帯を特定 const peakHours: number[] = []; const quietHours: number[] = []; for (const data of hourlyData) { if (data.avgUsers >= peakThreshold) { data.peakIndicator = true; peakHours.push(data.hour); } if (data.avgUsers <= quietThreshold) { quietHours.push(data.hour); } } return { hourlyData, peakHours, quietHours, }; }
- src/types.ts:331-347 (schema)TypeScript interfaces defining input (GetHourlyTrafficInput), data structure (HourlyData), and output (GetHourlyTrafficOutput) for the get_hourly_traffic tool.// get_hourly_traffic export interface GetHourlyTrafficInput extends PropertyId { period: ShortPeriod; } export interface HourlyData { hour: number; avgUsers: number; avgPageViews: number; peakIndicator: boolean; } export interface GetHourlyTrafficOutput { hourlyData: HourlyData[]; peakHours: number[]; quietHours: number[]; }
- src/server.ts:463-479 (registration)Tool registration in the tools array, defining name, description, and input schema for MCP server.{ name: "get_hourly_traffic", description: "時間帯別のアクセス状況を分析します。投稿やキャンペーンのタイミング最適化に活用できます。", inputSchema: { type: "object" as const, properties: { propertyId: { type: "string", description: "GA4プロパティID" }, period: { type: "string", enum: ["7days", "28days", "30days"], description: "集計期間", }, }, required: ["period"], }, },
- src/server.ts:718-722 (registration)Switch case in handleToolCall that routes get_hourly_traffic calls to the handler function.case "get_hourly_traffic": return await getHourlyTraffic({ propertyId: args.propertyId as string | undefined, period: args.period as "7days" | "28days" | "30days", });
- src/tools/analytics/index.ts:11-11 (helper)Re-export of getHourlyTraffic handler from its module for convenient import in server.ts.export { getHourlyTraffic } from "./getHourlyTraffic.js";