Get Website Stats

Instructions

Implementation Reference

• src/index.ts:552-564 (helper)

  TypeScript interfaces for API response data: WebsiteStatsRow and WebsitesStatsData. These define the shape of data returned from the /websites/stats endpoint.

  interface WebsiteStatsRow {
    result_type: string;
    estimated_traffic: number;
    estimated_traffic_change: number;
    number_of_keywords: number;
  }
  
  interface WebsitesStatsData {
    stats: WebsiteStatsRow[];
    estimated_traffic_sum: number;
    estimated_traffic_change_sum: number;
    number_of_keywords_sum: number;
  }

• src/index.ts:331-338 (schema)

  WebsiteStatsRowSchema - Zod schema for individual result-type rows (result_type, estimated_traffic, estimated_traffic_change, number_of_keywords).

  const WebsiteStatsRowSchema = z
    .object({
      result_type: z.string(),
      estimated_traffic: z.number(),
      estimated_traffic_change: z.number(),
      number_of_keywords: z.number(),
    })
    .passthrough();

• src/index.ts:384-391 (schema)

  WebsiteStatsOutputSchema - Zod output schema defining the full API response shape: stats array plus aggregated totals.

  const WebsiteStatsOutputSchema = z
    .object({
      stats: z.array(WebsiteStatsRowSchema),
      estimated_traffic_sum: z.number(),
      estimated_traffic_change_sum: z.number(),
      number_of_keywords_sum: z.number(),
    })
    .passthrough();

• src/index.ts:478-497 (schema)

  WebsiteStatsInputSchema - Zod input schema validating lang, type, target, optional scheme, and response_format.

  const WebsiteStatsInputSchema = z
    .object({
      lang: LangSchema,
      type: z
        .enum(WEBSITE_TYPES)
        .describe(
          "Target granularity: 'domain' (example.com), 'subdomain' (blog.example.com), 'prefix' (URL prefix), 'exact' (exact URL).",
        ),
      target: z
        .string()
        .min(3)
        .max(253)
        .describe("Target value (domain, subdomain, or URL, 3-253 chars)."),
      scheme: z
        .enum(WEBSITE_SCHEMES)
        .optional()
        .describe("URL scheme. Only relevant for type='exact' or 'prefix'."),
      response_format: ResponseFormatSchema,
    })
    .strict();

• src/index.ts:829-895 (handler)

  Complete tool registration and handler for marketing_miner_get_website_stats. Registers the tool with title, description, schemas, and implements the async handler: parses input, calls mmGet('/websites/stats', params), formats markdown table or JSON response, uses truncateIfNeeded for large payloads, and returns content with structured data.

    // -------------------------------------------------------------------------
    // Tool: website stats
    // -------------------------------------------------------------------------
    server.registerTool(
      "marketing_miner_get_website_stats",
      {
        title: "Get Website Stats",
        description: `Aggregate organic/paid traffic, keyword counts and result-type breakdown for a domain, subdomain, prefix, or exact URL.
  
  Args:
    - lang: Market code (cs/sk/pl/hu/ro/gb/us).
    - type: 'domain' | 'subdomain' | 'prefix' | 'exact'.
    - target: Target value (3-253 chars). Examples: 'seznam.cz', 'blog.seznam.cz', 'https://seznam.cz/email/'.
    - scheme (optional, for type='exact' or 'prefix'): 'https' | 'http'.
    - response_format: 'markdown' or 'json'.
  
  Returns: stats[] per result_type (organic, paid, ai_overviews, local_pack, images, videos, ...), plus totals (estimated_traffic_sum, number_of_keywords_sum).
  
  Use for competitor sizing, SEO audits, and SERP-feature distribution analysis.`,
        inputSchema: WebsiteStatsInputSchema.shape,
        outputSchema: WebsiteStatsOutputSchema.shape,
        annotations: {
          readOnlyHint: true,
          destructiveHint: false,
          idempotentHint: true,
          openWorldHint: true,
        },
      },
      async (args) => {
        const input = WebsiteStatsInputSchema.parse(args);
        try {
          const params: Record<string, unknown> = {
            lang: input.lang,
            type: input.type,
            target: input.target,
          };
          if (input.scheme) params.scheme = input.scheme;
          const data = await mmGet<WebsitesStatsData>("/websites/stats", params);
          const payload: Record<string, unknown> = { ...data };
          const md = [
            `# Website stats: \`${input.target}\` (${input.lang}, ${input.type})`,
            "",
            `- **Total estimated traffic**: ${data.estimated_traffic_sum}`,
            `- **Traffic change**: ${data.estimated_traffic_change_sum}`,
            `- **Total keywords**: ${data.number_of_keywords_sum}`,
            "",
            "| Result type | Traffic | Δ traffic | Keywords |",
            "|---|---|---|---|",
            ...data.stats.map(
              (s) =>
                `| ${s.result_type} | ${s.estimated_traffic} | ${s.estimated_traffic_change} | ${s.number_of_keywords} |`,
            ),
          ].join("\n");
  
          const text = input.response_format === "json" ? JSON.stringify(payload, null, 2) : md;
          const final = truncateIfNeeded(payload, text, "stats");
          return {
            content: [{ type: "text", text: final.text }],
            structuredContent: final.payload,
          };
        } catch (error) {
          return toolError(
            error instanceof Error ? error.message : `Unexpected error: ${String(error)}`,
          );
        }
      },
    );