market_share_query
Compose a market-share query with competitors, share/click metrics, and an optional breakdown in one call. Use it for multiple specific competitors or when the user explicitly requests the exact market_share_query tool. Honor an explicit exact-tool request even when competitors contains only "self": self-only keyword/page breakdowns execute through QWA's governed drill path (dynamic client comp{N} for Queries, page_market_share for Pages, and clicks_cpc_M for both). For ordinary natural-language self-only requests, prefer market_share_breakdown for ranked keyword/page rows and growth_vs_market_share for one filtered summary. Resolves "self" / "me" / "us" / "mine" / "my" → your share column; accepts competitor names, domains, labels, or comp{N} literals. IMPORTANT: when the user NAMES competitors (e.g. "our market share vs Competitor A and Competitor B"), pass them ALL DIRECTLY in competitors ALONGSIDE "self" (e.g. ["self","competitor-a.example","competitor-b.example"]) — this verb resolves each name/domain/label to its share column ITSELF, so do NOT call resolve_entity for individual competitors. A self-only page/category-filtered aggregate with no breakdown is rejected with a steer to growth_vs_market_share. Per segment — without one it defaults to the primary "default" (Overall Market) segment. UNIT CONTRACT: market-share values are already percentage units on a 0–100 scale (0.03 means 0.03%, not 3%); share delta is selected-minus-comparison percentage points; leader gap is leader-minus-client percentage points for the same period; only deltaPct is a relative-change ratio.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"date_range": "<date_range>"
},
"name": "market_share_query"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| brand | No | Restrict to branded ("Yes") or non-branded ("No") demand (ignored at site granularity) | |
| grain | No | Granularity: keyword/page for per-row GSC metrics, site/segment for share-only (clicks blocked by a known SQL bug at those grains). 'category' is NOT supported for share vs competitors (no member carries categories AND comp{N}) — it returns a clear steer. | keyword |
| top_n | No | Maximum rows to return (max 200; only meaningful when breakdown_by is set). | |
| intent | No | Restrict to ONE search intent, e.g. "Informational" (a single-value filter, not a breakdown — for top-N across intents use market_share_breakdown; ignored at site granularity) | |
| medium | No | competitor source medium for the comparison, e.g. "google/organic" (default) or "google/cpc" | |
| filters | No | Additional filters with operators (matches the UI). e.g. keyword contains "vps" but not "pricing": [{field:"keyword",op:"contains",value:"vps"},{field:"keyword",op:"not_contains",value:"pricing"}]; country in usa,can: [{field:"country",op:"eq",value:["usa","can"]}]; device desktop: [{field:"device",op:"eq",value:"DESKTOP"}]. regex/not_regex only on keyword/page. | |
| metrics | No | Which metrics to include. "impressions" and "ctr" are a fast-follow (not yet live-verified at keyword grain). | |
| segment | No | Tracked segment ID; omit to default to the primary "default" (Overall Market) segment | |
| sort_by | No | Sort field: "clicks"; "market_share"/"share"/"our share" or any self alias (self/me/us/mine/my) for your share; or the name/domain of a competitor in the competitors list. A self-share sort requires a self alias in competitors. Invalid keys are rejected instead of silently falling back. Defaults to clicks when available, else the first requested share. | |
| date_range | Yes | Explicit date range, e.g. "2026-05-01 to 2026-05-31". Both endpoints are INCLUSIVE — the END day is covered (a 7-day range = 7 days). Quattr weeks run Sunday–Saturday; for "last week" use the most recent complete Sun–Sat span. | |
| competitors | No | Competitor identifiers: "self" / "me" / "us" / "mine" / "my" = your own share; a domain/label substring = that competitor; "comp3" = column comp3. When the user names competitors (e.g. "vs Competitor A and Competitor B"), pass them DIRECTLY here ALONGSIDE "self" — e.g. ["self","competitor-a.example","competitor-b.example"]; this verb maps each name/domain to its share column, so do NOT resolve_entity individual competitors. The default ["self"] returns ONLY your own share (no competitor columns). | |
| breakdown_by | No | Optional group-by field: intent, keyword, or page. Omit for a single aggregate row across the whole segment. |