get_geo_breakdown
Retrieve geographic breakdown reports from Google Analytics 4 data to analyze user traffic by country or city over specified time periods.
Instructions
地域別（国または市区町村）のアクセス分析結果を取得します。
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| propertyId | No | GA4プロパティID | |
| period | Yes | 集計期間 | |
| level | Yes | 地域レベル | |
| limit | No | 取得件数（デフォルト: 10） |
Implementation Reference
- The main handler function implementing the get_geo_breakdown tool logic. It executes a GA4 report for country or city breakdown, calculates percentages, and returns location data.export async function getGeoBreakdown( input: GetGeoBreakdownInput ): Promise<GetGeoBreakdownOutput> { const propertyId = getPropertyId(input.propertyId); const property = formatPropertyPath(propertyId); const dateRange = periodToDateRange(input.period); const limit = input.limit || 10; // level に応じてディメンションを選択 const dimension = input.level === "city" ? "city" : "country"; const response = await executeReport({ property, dateRanges: [dateRange], dimensions: [{ name: dimension }], metrics: [{ name: "totalUsers" }, { name: "sessions" }], orderBys: [{ metric: { metricName: "totalUsers" }, desc: true }], limit, }); // 合計ユーザー数を取得 const totalUsers = response.totals?.[0]?.metricValues?.[0]?.value ? parseFloat(response.totals[0].metricValues[0].value) : 0; const locations: LocationData[] = []; for (const row of response.rows || []) { const dimensionValues = row.dimensionValues || []; const metricValues = row.metricValues || []; const getValue = (index: number): number => { const value = metricValues[index]?.value; return value ? parseFloat(value) : 0; }; const users = Math.round(getValue(0)); locations.push({ name: dimensionValues[0]?.value || "(不明)", users, sessions: Math.round(getValue(1)), percentage: calculatePercentage(users, totalUsers), }); } return { locations }; }
- src/types.ts:204-220 (schema)TypeScript interfaces defining the input schema (GetGeoBreakdownInput), supporting LocationData, and output schema (GetGeoBreakdownOutput) for the tool.// get_geo_breakdown export interface GetGeoBreakdownInput extends PropertyId { period: ShortPeriod; level: "country" | "city"; limit?: number; } export interface LocationData { name: string; users: number; sessions: number; percentage: string; } export interface GetGeoBreakdownOutput { locations: LocationData[]; }
- src/server.ts:286-310 (registration)Tool registration in the tools array, including name, description, and inputSchema for MCP server.{ name: "get_geo_breakdown", description: "地域別（国または市区町村）のアクセス分析結果を取得します。", inputSchema: { type: "object" as const, properties: { propertyId: { type: "string", description: "GA4プロパティID" }, period: { type: "string", enum: ["7days", "28days", "30days"], description: "集計期間", }, level: { type: "string", enum: ["country", "city"], description: "地域レベル", }, limit: { type: "number", description: "取得件数（デフォルト: 10）", }, }, required: ["period", "level"], }, },
- src/server.ts:663-669 (registration)Dispatch handler in the switch statement that calls the getGeoBreakdown function with parsed arguments.case "get_geo_breakdown": return await getGeoBreakdown({ propertyId: args.propertyId as string | undefined, period: args.period as "7days" | "28days" | "30days", level: args.level as "country" | "city", limit: args.limit as number | undefined, });
- src/tools/analytics/index.ts:5-5 (helper)Re-export of the getGeoBreakdown handler from its module for use in server.ts.export { getGeoBreakdown } from "./getGeoBreakdown.js";