get_geo_breakdown
Retrieve geographic breakdown analysis from Google Analytics 4 data by country or city to understand regional traffic patterns and user distribution.
Instructions
地域別（国または市区町村）のアクセス分析結果を取得します。
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| propertyId | No | GA4プロパティID | |
| period | Yes | 集計期間 | |
| level | Yes | 地域レベル | |
| limit | No | 取得件数（デフォルト: 10） |
Implementation Reference
- The main asynchronous handler function that implements the core logic for the get_geo_breakdown tool, querying GA4 for geographic breakdown data by country or city.
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 (GetGeoBreakdownInput), supporting types (LocationData), and output (GetGeoBreakdownOutput) for the get_geo_breakdown 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)Registration of the get_geo_breakdown tool in the tools array, defining its name, description, and input schema for MCP.
{ 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 within handleToolCall that routes calls to the get_geo_breakdown tool to its implementation.
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, allowing it to be imported in server.ts.
export { getGeoBreakdown } from "./getGeoBreakdown.js";