market_share_breakdown
Use for market share broken down by intent, language, keyword, page, content category, branded/non-branded demand, rank bucket, or country. Returns one governed row per slice with the QWA-compatible share and, where the surface exposes it, clicks. For languages, countries, queries, or pages within one rank bucket, pass the matching breakdown_by plus rank_bucket:"Ranking 1 to 3" (after resolving the exact value). The language/query/page routes apply the bucket directly to the governed market-share drill. Pass country with breakdown_by:"keyword" for QWA's country-to-Queries drill; pass country or device with breakdown_by:"page"/"keyword" for other filtered rows such as “top pages in Canada”. Pass category with breakdown_by:"page" for “pages within Help”; pass page with breakdown_by:"page" or "keyword" for rows within one URL pattern such as "%/products/%". Page/category filters are rejected on language/intent/brand/category/rank_bucket/country because those sources cannot apply the scope faithfully. Pass comparison_range for per-row deltas. For “largest market-share gains/losses” across pages, queries, or countries, use sort_by:"market_share_change" plus change_direction:"gain"|"loss"; that mode ranks the same broad comparison candidate population as QWA (every country row in both periods) instead of the current-period top rows. This is the ONLY market-share verb that groups by a field and returns multiple ranked rows; prefer it over market_share_query for a single-self top-N page/keyword breakdown. 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_breakdown"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Restrict a keyword/page breakdown to one page/URL pattern, e.g. "%/products/%". Uses QWA page_segment semantics and is not a replacement for breakdown_by:"page". | |
| brand | No | Restrict to branded ("Yes") or non-branded ("No") demand (ignored at site granularity) | |
| top_n | No | How many top rows to return (max 200) | |
| device | No | Restrict a keyword/page breakdown to one resolved device value, e.g. "DESKTOP". Uses QWA device_segment semantics. Resolve the exact value with list_filter_values first. | |
| intent | No | Restrict to ONE intent as an additional filter — meaningful when breakdown_by is language/keyword/page; ignored when breakdown_by is intent | |
| medium | No | competitor source medium for the comparison, e.g. "google/organic" (default) or "google/cpc" | |
| country | No | Restrict a keyword/page breakdown to one resolved country code, e.g. "can". Keyword breakdowns mirror QWA's direct country-to-Queries drill; page breakdowns retain QWA country_segment semantics. Resolve the exact value with list_filter_values first. | |
| segment | No | Tracked segment ID; omit to use the primary "default" (Overall Market) segment. | |
| sort_by | No | Rank rows by current clicks (default), current market share, or period-over-period market-share change. market_share_change requires comparison_range and is supported for breakdown_by page, keyword, or country; it ranks across every comparison candidate after computing deltas, not a current-value top-N subset. | clicks |
| category | No | Restrict a keyword/page breakdown to one resolved content category. Use this for “pages within Help”; resolve the exact category value first. | |
| competitor | No | Optional competitor domain or label to include its per-row share, e.g. "competitor-a.example" or "comp3" | |
| 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. | |
| rank_bucket | No | Restrict a language, country, query, or page breakdown to ONE QWA rank bucket, e.g. "Ranking 1 to 3". Resolve the exact value with list_filter_values(rank_bucket) first. This is a filter; use breakdown_by:"rank_bucket" to return all rank buckets. | |
| breakdown_by | No | What to break the metrics down across. language mirrors QWA’s Language tab; brand returns Branded vs Non-branded; rank_bucket mirrors QWA rank bands; country mirrors the Countries tab. | intent |
| change_direction | No | When sort_by is market_share_change, return the largest gains (default) or losses. Ignored for current-value sorts. | gain |
| comparison_range | No | Explicit comparison range for period-over-period, e.g. "2026-04-01 to 2026-04-30". Adds per-row deltas (delta + deltaPct) for clicks and shares — the Quattr app's "% change" columns. |