Ranking position distribution
get_position_distributionSlices a property by where it ranks, using the same 1-3 / 4-10 / 11-20 / 21+ bands as the GSC Wizard dashboard. granularity "period" (default) returns impressions, clicks and the number of queries (or pages) in each band over the whole range, showing how top-heavy the property's visibility is. granularity "daily" returns one row per day with the count of DISTINCT queries ranking in each band, which is how you see a ranking shift build up or a drop land on a specific date. Positions are impression-weighted averages, so a row sits in one band only. Served from the GSC Wizard ClickHouse warehouse when available (both views are computed in the warehouse over every query or page, never truncated; scanLimit is null there), otherwise from the live Search Console API over the top scanLimit rows by clicks, which drops zero-click rows first and so understates the deep bands when truncated is true (see dataSource). Date range is optional: omit startDate/endDate to analyze the last 28 settled days (data lags ~2-3 days).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| endDate | No | Optional. Window end as YYYY-MM-DD (e.g. 2026-05-31). You do NOT need to know today's date or the latest available date: omit this and the server uses the latest settled Search Console date (data lags ~2-3 days behind today). Never pass null or the string "null". | |
| siteUrl | Yes | ||
| dimension | No | What a "row" is on the period path: a search query or a page. | query |
| scanLimit | No | How many top rows by clicks to bucket on the live Search Console API. Raise it when a long-tail property reports `truncated: true`. Ignored on the ClickHouse warehouse, which buckets every row in SQL. | |
| startDate | No | Optional. Window start as YYYY-MM-DD (e.g. 2026-05-03). You do NOT need to know today's date. Omit BOTH startDate and endDate to analyze the last 28 settled days automatically (Search Console data lags ~2-3 days). Never pass null or the string "null". | |
| searchType | No | web | |
| granularity | No | "period" = one bucket summary over the range; "daily" = distinct query counts per band per day (always keyed on query, ignores `dimension`). | period |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | ||
| note | No | ||
| range | No | ||
| totals | No | ||
| buckets | No | ||
| siteUrl | No | ||
| dayTotals | No | ||
| dimension | No | ||
| scanLimit | No | ||
| truncated | No | ||
| dataSource | No | ||
| searchType | No | ||
| granularity | No | ||
| dataMaturity | No | ||
| settledThrough | No | ||
| warehouseLatestDate | No |