at-mintel/packages/seo-engine/src/agents/serper-agent.ts

import axios from "axios";

export interface SerperResult {
  relatedSearches: string[];
  peopleAlsoAsk: string[];
  organicSnippets: string[];
  estimatedTotalResults: number;
}

/**
 * Fetch Google search data via Serper's /search endpoint.
 * Extracts related searches, People Also Ask, organic snippets,
 * and totalResults as a search volume proxy.
 */
export async function fetchSerperData(
  query: string,
  apiKey: string,
  locale: { gl: string; hl: string } = { gl: "de", hl: "de" },
): Promise<SerperResult> {
  try {
    const response = await axios.post(
      "https://google.serper.dev/search",
      {
        q: query,
        gl: locale.gl,
        hl: locale.hl,
      },
      {
        headers: {
          "X-API-KEY": apiKey,
          "Content-Type": "application/json",
        },
      },
    );

    const data = response.data;

    const relatedSearches =
      data.relatedSearches?.map((r: any) => r.query) || [];
    const peopleAlsoAsk = data.peopleAlsoAsk?.map((p: any) => p.question) || [];
    const organicSnippets = data.organic?.map((o: any) => o.snippet) || [];
    const estimatedTotalResults = data.searchInformation?.totalResults
      ? parseInt(data.searchInformation.totalResults, 10)
      : 0;

    return {
      relatedSearches,
      peopleAlsoAsk,
      organicSnippets,
      estimatedTotalResults,
    };
  } catch (error) {
    console.error(
      `Serper API error for query "${query}":`,
      (error as Error).message,
    );
    return {
      relatedSearches: [],
      peopleAlsoAsk: [],
      organicSnippets: [],
      estimatedTotalResults: 0,
    };
  }
}