SEO
Google Search Analytics API Adds Branded Classification, Web Multimodal Lens Data, and Multi-Value filterLists
Announced November 16, 2026, Google's Search Analytics API update adds native brandedClassification grouping, webMultimodal metrics for Google Lens and Circle to Search, and multi-country/multi-device filterLists batching. Here is the schema reference, 22-site field test evidence, and Python ETL migration guide.
8 min read
Google Search Analytics API Adds Branded Classification, Web Multimodal Lens Data, and Multi-Value filterLists
Executive Summary
On November 16, 2026, Google's Search Console team announced new filtering and reporting capabilities in the Search Analytics API, bringing API parity to three features previously restricted to the Search Console web UI. Developers and SEO engineering teams can now query:
brandedClassification(BRANDED/NON_BRANDED): Native grouping and filtering for branded vs. non-branded search traffic, available from February 21, 2026 onward for eligible top-level properties.type: "webMultimodal": Isolated performance metrics (clicks, impressions, CTR, position) from Google Lens, Circle to Search on Android, and image uploads in Google Search, also flowing into BigQuery for properties with an active bulk data export.dimensionFilterGroups[].filterLists[]: Multi-value exact-match filtering across multiple ISO 3166-1 alpha-3countrycodes ordevicetypes (DESKTOP,MOBILE,TABLET) in a single POST request.
As Search Engine Land reported on November 16, 2026, these additions eliminate brittle keyword regex lists and multi-request country stitching. Independent field testing across 22 sites published the same day by podrez.pl shows why brandedClassification matters mathematically: visible query rows covered only 45% of total clicks on average (ranging from 8% to 57%) due to Search Console's anonymized-query privacy filtering, whereas BRANDED plus NON_BRANDED matched 100% of total site clicks on every eligible property. Confidence is high on all API schemas and constraints (verified against the Search Analytics: query API reference), and partial on the exact brandedClassification impression threshold because Google documents only "sufficient query and impression volume" without publishing a fixed cutoff.
Technical Mechanics and Architecture
Before November 16, 2026, automated SEO pipelines calling POST /webmasters/v3/sites/{siteUrl}/searchAnalytics/query faced three structural blind spots:
- Anonymized Query Loss: Regex filters on the
querydimension only evaluated visible queries, silently dropping anonymized tail queries from branded/non-branded splits. - Blended Visual Discovery: Traffic from Google Lens, Circle to Search, and image uploads could not be isolated via the API's
typeparameter. - 1:1 Filter Cardinality:
dimensionFilterGroups[].filters[]only accepted a single expression per entry, forcing ETL jobs to issueNseparate API calls forNcountries (such as DACH, EMEA, or LATAM rollups) and manually compute impression-weighted average position.
[Automated SEO / BI Pipeline]
|
v POST .../searchAnalytics/query (Single Batched Request)
+-------------------------------------------------------------------+
| Request Controls (Nov 16, 2026 Schema) |
| - type: "web" | "webMultimodal" | "image" | "video" | ... |
| - dimensions: ["brandedClassification", "page", "date"] |
| - filterLists[]: { dimension: "country", expressions: ["DEU","AUT","CHE"] }
| { dimension: "device", expressions: ["MOBILE","DESKTOP"] }
+-------------------------------------------------------------------+
|
+---> [Eligible Top-Level Property?] --No--> Empty rows [] (no error!)
|
v Yes (Sufficient volume, >= 2026-02-21)
+-------------------------------------------------------------------+
| Search Console Analytics Engine |
| - Classifies ALL clicks (visible + anonymized) into BRANDED/NON |
| - Isolates Lens / Circle to Search under webMultimodal |
| - Computes combined totals & weighted position across filterLists|
+-------------------------------------------------------------------+
|
v
[JSON Response / Search Console BigQuery Bulk Data Export]
Hard API Constraints to Respect
Per the official Search Analytics: query documentation, four validation rules will break naive integrations if overlooked:
- No
query+brandedClassificationin the same request: Filtering or grouping bybrandedClassificationcannot be combined with aqueryfilter in the same request. - Only
equalsoperator onbrandedClassification: When used insidefilters[], onlyoperator: "equals"is supported with values"BRANDED"or"NON_BRANDED". - No duplicate dimensions across
filtersandfilterLists: A single request cannot filter on the same dimension (e.g.,country) in bothfilters[]andfilterLists[]simultaneously. - Silent empty response for ineligible properties:
brandedClassificationonly returns rows for top-level properties with sufficient query and impression volume (data starting2026-02-21). Ineligible properties (such as URL-prefix sub-folders or low-volume sites) receive200 OKwith zero rows rather than an error.
Defensive Python API Client (Read-Only Query & Eligibility Guard)
The Python snippet below demonstrates how to query brandedClassification, webMultimodal, and filterLists safely using google-api-python-client, with explicit validation against the API's mutual-exclusion rules and silent-empty-row detection:
#!/usr/bin/env python3
"""Read-only Google Search Analytics API query helper for Nov 2026 features."""
from typing import Any, Dict, List
def build_branded_regional_payload(
start_date: str,
end_date: str,
countries: List[str],
devices: List[str],
) -> Dict[str, Any]:
"""Build a valid Search Analytics query for branded split across regions."""
return {
"startDate": start_date,
"endDate": end_date,
"type": "web",
"dimensions": ["brandedClassification", "date"],
"dimensionFilterGroups": [
{
"groupType": "and",
"filterLists": [
{"dimension": "country", "expressions": countries},
{"dimension": "device", "expressions": devices},
],
}
],
"rowLimit": 1000,
}
def build_multimodal_pages_payload(
start_date: str,
end_date: str,
countries: List[str],
) -> Dict[str, Any]:
"""Query Google Lens & Circle to Search page performance (no query dimension)."""
return {
"startDate": start_date,
"endDate": end_date,
"type": "webMultimodal",
"dimensions": ["page", "country", "device"],
"dimensionFilterGroups": [
{
"groupType": "and",
"filterLists": [{"dimension": "country", "expressions": countries}],
}
],
"rowLimit": 5000,
}
def run_safe_query(service: Any, site_url: str, body: Dict[str, Any]) -> List[Dict[str, Any]]:
"""Execute Search Analytics query and warn on silent empty branded responses."""
resp = service.searchanalytics().query(siteUrl=site_url, body=body).execute()
rows = resp.get("rows", [])
if not rows and "brandedClassification" in body.get("dimensions", []):
print(
f"[WARN] {site_url}: 0 rows returned for brandedClassification. "
"Verify top-level property scope, >= 2026-02-21 dates, and impression volume."
)
return rows
Evidence: Before vs. After & 22-Site Field Test Data
The table below compares the Search Analytics API before and after November 16, 2026, combining Google's official documentation with empirical API measurements across 22 sites (83,060 clicks and 4.32 million impressions from October 17 to November 13, 2026) published by podrez.pl.
| Capability | Pre-Nov 16, 2026 API | Post-Nov 16, 2026 API | Verified Field Behavior |
|---|---|---|---|
| Branded vs. Non-Branded | Manual regex on query; anonymized queries excluded |
brandedClassification (BRANDED, NON_BRANDED) as dimension or equals filter |
12/22 tested sites qualified; observed threshold between 23,733 and 29,212 28-day impressions; 100% click parity vs 45% visible-query average |
| Visual / Multimodal Search | Unavailable in API (web, image, video, news, discover, googleNews only) |
type: "webMultimodal" (Google Lens, Circle to Search, image uploads) + BigQuery export |
Cannot be grouped by query; supports page, country, device, date |
| Multi-Country Filtering | 1 request per country + manual weighted-position math | filterLists[] with ISO 3166-1 alpha-3 array (e.g., ["DEU", "AUT", "CHE"]) |
Server-side totals and impression-weighted position computed automatically |
| Multi-Device Filtering | Separate requests or post-query grouping | filterLists[] with ["DESKTOP", "MOBILE", "TABLET"] |
Cannot overlap device in both filters[] and filterLists[] |
Key Analytical Takeaways
- Why
brandedClassificationchanges executive reporting: When teams relied on regex filters over visible queries, up to55%(or more) of clicks were invisible due to privacy anonymization. BecausebrandedClassificationruns server-side before query-row suppression,BRANDED + NON_BRANDEDsums cleanly to total site clicks on qualifying properties. - Multimodal search is page-centric, not keyword-centric: Because
webMultimodalrepresents camera/visual queries (Google Lens, Circle to Search on Android, and image uploads), you cannot groupwebMultimodaldata byquery. Instead, pairtype: "webMultimodal"with["page", "country", "device"]—or inspect it in BigQuery Bulk Data Export—to see which product or editorial URLs win visual discovery. - BigQuery & Quota Efficiency: For agencies tracking 10-country regional hubs like EMEA or LATAM, replacing 10 sequential country requests with one
filterListsrequest cuts API quota burn and eliminates floating-point rounding drift in average-position calculations.
Implementation & Migration Playbook
Follow these numbered steps to adopt the November 16, 2026 Search Analytics API features without breaking existing dashboards:
1. Audit Property Eligibility Before Replacing Brand Regex
Do not delete your existing brand-regex fallback blindly. Run a dry-run query with dimensions: ["brandedClassification"] for a recent 28-day window (ensuring startDate >= 2026-02-21) on every Search Console property:
- Confirm the property is a top-level Domain or URL-prefix property (sub-folder properties are ineligible).
- If
rowsreturns empty ([]), keep your legacy regex pipeline active for that low-volume property until it crosses Google's impression threshold.
2. Separate query-Level and brandedClassification ETL Jobs
Because the API rejects requests that combine brandedClassification with a query filter, split your ETL into two distinct jobs:
- Job A (Executive Brand Share):
dimensions: ["brandedClassification", "date"]+filterListsfor regional hubs. - Job B (Keyword-Level Diagnostics): Existing
dimensions: ["query", "page"]pipeline withoutbrandedClassification.
3. Add webMultimodal Ingestion to Search Console & BigQuery
Add a dedicated type: "webMultimodal" pull (grouped by ["page", "country", "device", "date"]) to your ingestion DAG, or update your BigQuery SQL views if you use Search Console Bulk Data Export so visual search clicks from Google Lens and Circle to Search are tracked separately from type: "web" and type: "image".
4. Refactor Multi-Country Loops to filterLists
Replace per-country API loops (such as iterating over DEU, AUT, CHE for DACH) with a single filterLists array:
{
"startDate": "2026-10-18",
"endDate": "2026-11-14",
"dimensions": ["date", "page"],
"dimensionFilterGroups": [
{
"groupType": "and",
"filterLists": [
{ "dimension": "country", "expressions": ["DEU", "AUT", "CHE"] },
{ "dimension": "device", "expressions": ["MOBILE", "DESKTOP"] }
]
}
]
}
5. Rollback & Schema Validation
Before deploying updated ETL scripts to production, validate that no request places the same dimension (country or device) in both filters[] and filterLists[] (which triggers an HTTP 400 error), and retain a feature flag to revert to single-country filters[] if downstream BI tables expect per-country rows.
Frequently Asked Questions (FAQ)
When did Google add brandedClassification, webMultimodal, and filterLists to the Search Analytics API?
Google's Search Console team announced all three additions on November 16, 2026 via the Google Search Central Blog and updated the searchAnalytics.query API reference.
Why does brandedClassification return an empty response for some sites?
brandedClassification is only available for eligible top-level properties with sufficient query and impression volume, with historical data starting February 21, 2026. Ineligible properties receive an empty rows array rather than an error.
Does brandedClassification include anonymized queries?
Yes. Independent testing across 22 sites on November 16, 2026 confirmed that BRANDED plus NON_BRANDED clicks matched 100% of total site clicks on eligible properties, capturing anonymized clicks that regex filters on visible query rows miss.
Can I group webMultimodal data by query?
No. type: "webMultimodal" (which covers Google Lens, Circle to Search on Android, and image uploads in Google Search) does not support grouping by query; group by page, country, device, or date instead.
Can I use filters[] and filterLists[] on the same dimension?
No. According to the Search Analytics API documentation, a single request cannot filter on the same dimension in both filters and filterLists at the same time.
Sources
- Google Search Central Blog: New filtering and reporting capabilities in the Search Analytics API (Published November 16, 2026)
- Google for Developers: Search Analytics: query | Search Console API (Updated November 2026)
- Search Engine Land: Google Search Analytics API gains new filters and reporting (Published November 16, 2026)
- podrez.pl: Search Console API: Branded Queries and Lens Data on 22 Sites (Published November 16, 2026)