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.

By 0xScorPionSon

8 min read

Google Search Analytics API Adds Branded Classification, Web Multimodal Lens Data, and Multi-Value filterLists

Google Search Analytics API brandedClassification webMultimodal filterLists infographic

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:

  1. 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.
  2. 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.
  3. dimensionFilterGroups[].filterLists[]: Multi-value exact-match filtering across multiple ISO 3166-1 alpha-3 country codes or device types (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:

  1. Anonymized Query Loss: Regex filters on the query dimension only evaluated visible queries, silently dropping anonymized tail queries from branded/non-branded splits.
  2. Blended Visual Discovery: Traffic from Google Lens, Circle to Search, and image uploads could not be isolated via the API's type parameter.
  3. 1:1 Filter Cardinality: dimensionFilterGroups[].filters[] only accepted a single expression per entry, forcing ETL jobs to issue N separate API calls for N countries (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 + brandedClassification in the same request: Filtering or grouping by brandedClassification cannot be combined with a query filter in the same request.
  • Only equals operator on brandedClassification: When used inside filters[], only operator: "equals" is supported with values "BRANDED" or "NON_BRANDED".
  • No duplicate dimensions across filters and filterLists: A single request cannot filter on the same dimension (e.g., country) in both filters[] and filterLists[] simultaneously.
  • Silent empty response for ineligible properties: brandedClassification only returns rows for top-level properties with sufficient query and impression volume (data starting 2026-02-21). Ineligible properties (such as URL-prefix sub-folders or low-volume sites) receive 200 OK with 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

  1. Why brandedClassification changes executive reporting: When teams relied on regex filters over visible queries, up to 55% (or more) of clicks were invisible due to privacy anonymization. Because brandedClassification runs server-side before query-row suppression, BRANDED + NON_BRANDED sums cleanly to total site clicks on qualifying properties.
  2. Multimodal search is page-centric, not keyword-centric: Because webMultimodal represents camera/visual queries (Google Lens, Circle to Search on Android, and image uploads), you cannot group webMultimodal data by query. Instead, pair type: "webMultimodal" with ["page", "country", "device"]—or inspect it in BigQuery Bulk Data Export—to see which product or editorial URLs win visual discovery.
  3. BigQuery & Quota Efficiency: For agencies tracking 10-country regional hubs like EMEA or LATAM, replacing 10 sequential country requests with one filterLists request 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 rows returns 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"] + filterLists for regional hubs.
  • Job B (Keyword-Level Diagnostics): Existing dimensions: ["query", "page"] pipeline without brandedClassification.

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

More on SEO

SEO

Gemini 4 Hydrogen Becomes Google AI Mode's Default Model—Expanding Query Fan-Out Mid-Core Update

On November 12, 2026, Google made Gemini 4 Hydrogen the global default model in Search AI Mode and routed the hardest AI Overview questions to it—just 48 hours after launching the November 2026 Core Update. Here is how Hydrogen's query fan-out and structured outputs work, why Google published no link-count benchmarks, and how SEO engineers can isolate AI Mode shifts from core ranking volatility.

10 min read

SEO

ChatGPT Business Hub Gives Sites First-Party AI Click Counts, But Leaves Critical Measurement Blind Spots

OpenAI launched ChatGPT Business Hub in beta on November 10, 2026, giving verified businesses their first direct view into 7-day and 28-day website mentions, recorded clicks, and discovery topics. Early telemetry—such as Search Engine Journal's 353,356 mentions and 2,663 clicks—proves the channel is measurable, but strict counting definitions and missing prompt logs mean teams must pair Hub Insights with server-side referral auditing.

11 min read

Tell us what is not working

A thirty-minute call, no deck and no obligation. You will leave with a straight answer about whether this is worth building - including if that answer is no.

Start a project

Direct line

hello@codebumble.net
Dhaka, Bangladesh  :   local timeCalls in English or Bangla