List every verified Search Console property accessible to this service account.

Returns: {"sites": [{siteUrl, permissionLevel}, ...], "count": N}. permissionLevel: siteOwner | siteFullUser | siteRestrictedUser | siteUnverifiedUser.

Call this first. URL Inspection requires siteFullUser or siteOwner; restricted users cannot inspect.

Query Search Console traffic data - clicks, impressions, CTR, position.

THE workhorse tool. Supports all six dimensions (incl. HOUR, April 2025), all six search types, full filter compose, pagination, and auto-pagination.

Args: site_url: "https://example.com/" (URL-prefix) or "sc-domain:example.com" (domain). start_date / end_date: YYYY-MM-DD (Pacific Time). 16-month retention hard cap. dimensions: list of {date, query, page, country, device, searchAppearance, HOUR}. HOUR requires data_state='hourly_all'. searchAppearance cannot be combined with other dimensions in one query - query it alone and join client-side. search_type: web (default) | image | video | news | discover | googleNews. filters: flat list [{dimension, operator, expression}]. Operators: equals, contains, notEquals, notContains, includingRegex, excludingRegex. filter_groups: advanced - pass raw dimensionFilterGroups if you need OR logic. Mutually exclusive with filters. aggregation_type: auto (default) | byPage | byProperty | byNewsShowcasePanel. data_state: final (default, ~2-3d lag) | all (fresh, includes unfinalized) | hourly_all (~10d history with HOUR dimension). row_limit: per-call cap, 1–25000 (API hard cap). start_row: 0-based offset for single-page paging. max_rows: if set (up to 1M), auto-paginate until exhausted or max_rows hit.

Response: {rows, row_count, response_aggregation_type, first_incomplete_date?, first_incomplete_hour?, metadata}. Use first_incomplete_date to distinguish 'data still cooking' from 'data is final' when data_state != 'final'.

Gotchas:

• 16-month retention. start_date older than 16 months returns empty.

• Anonymized queries (fewer than ~a dozen users over 2-3 months) drop from the 'query' dimension but count in totals - page-level data is more complete.

• Aggregation shift: with a page filter, totals aggregate byPage (inflates clicks vs property-level). Set aggregation_type explicitly when comparing.

• searchAppearance cannot co-exist with other dimensions (API 400).

List sitemaps on a site - or fetch one sitemap by feedpath.

Args: site_url: the Search Console property. sitemap_index: optional - if set, list only the children of a sitemap-index URL (e.g. "https://example.com/sitemap_index.xml"). feedpath: optional - if set, returns the single sitemap entry at that URL instead of the list (absorbs the prior get_sitemap tool).

Returns: {"sitemaps": [...], "count": N} or {"sitemap": {...}} if feedpath given. Each entry: {path, lastSubmitted, lastDownloaded, isPending, isSitemapsIndex, type, warnings, errors, contents}.

Inspect a URL in the Google index. Flattened response.

Checks index status, coverage state, canonical URLs, crawl info, AMP status, and rich results. Does NOT trigger a live crawl - checks Google's current index snapshot only.

Args: inspection_url: fully-qualified URL to inspect (must be under the property). site_url: the Search Console property - "https://example.com/" or "sc-domain:example.com". language_code: IETF BCP-47, default "en-US".

Quota: 2,000 requests/day/site + 600 requests/minute/site. Requires the SA to be a Full user on the property (Restricted users get 403 here).

Returns a flat dict with top-level verdict, coverage_state, canonical info, plus optional amp and rich_results sub-objects. _raw has the full untouched payload.

Inspect many URLs under a single Search Console property. Rate-limited.

Respects Google's 600 QPM / 2,000 QPD per-site limits. Default pace of 8 QPS stays well under 600/minute with headroom. For large jobs (>2000 URLs), split across days or across multiple verified properties (e.g. per-subdomain).

Args: urls: list of fully-qualified URLs under site_url. No dedup. site_url: the Search Console property. language_code: BCP-47, default "en-US". requests_per_second: pace. Max ~10 (600 QPM). Caller can lower on 429 pressure. continue_on_error: if True, collect per-URL errors instead of aborting.

Returns: { "results": [{"url": str, "inspection": {...flattened...}} | {"url": str, "error": str}], "count": total, "errors": N, "skipped": 0 }

Quota warning: This does NOT replace the Search Analytics API for bulk query analysis. If the intent is "which pages have most traffic", use gsc_query_search_analytics instead - 40,000 QPM per project vs 600/site here.