Analyze the structural shape of the AI-generated answer actually
cited for a keyword: does it lead with a list, how long is the opening
passage, how many sources does it cite and from which domains. Use
this to understand what a winning AI-search answer looks like for a
topic, e.g. before writing content meant to get cited.
Read-only: no side effects, safe to retry. Costs 1 quota unit per sample
(1 by default; free tier is 30 units/month shared across every metered
tool, so up to 30 single-sample calls to this tool alone if nothing else
is used that period).
Returns: {"keyword", "engine", "model" (the answering model's version, as
the provider reports it), "checked_at" (when the answer was fetched, UTC),
"leads_with_list" (bool), "opening_word_count"
(int), "opening_has_number" (bool), "outline" (list of up to 12 section
heads, in order: the answer's headings, or its top-level list items when it
has fewer than two headings; heads only, never the text under them),
"has_table" (bool), "num_sources_cited" (int),
"source_domains" (list of up to 10 domain strings), "source_mix"
({"community_pct" (share of those sources that are community sites such
as Reddit, YouTube, X, Quora), "community_domains", "other_domains"}),
"country", "language"}. With samples above 1 the shape fields describe
the first answer, plus "samples_ok" (answers that came back) and
"source_frequency" (list of {"domain", "runs"}: how many of the answers
cited each domain, most often first). Answers change from run to run, so
a domain cited in every sample is a far stronger signal than one sample.
Use analyze_citation_structure_batch instead if you need this for more than
one keyword - one call per topic here adds up fast for a cluster. Use
analyze_citation_gap instead if you have your own page for this
keyword and want the gap to the winner, not just the winner's shape.
Args:
keyword: the topic/query to analyze, e.g. "how to reduce churn".
country: market to read the answer in, e.g. "Italy". Defaults to
"United States". For perplexity a 2-letter code also works.
language: language code, e.g. "it". Defaults to "en". Write the
keyword in that language too.
engine: "chat_gpt" (default), "gemini" or "perplexity". chat_gpt and
gemini are the answers a person sees in those apps; perplexity is
Perplexity's sonar API with web search.
samples: how many independent answers to read, 1 to 5. Default 1.
