Skip to content
Climb Google Maps: Google Business Profile optimization.

Google

The Search Console API Now Splits Branded Traffic, Lens Searches and Country Groups: What Changed, and a Script That Uses All Three

Google added the branded queries filter, web multimodal data from Lens and Circle to Search, and multi-country and multi-device filters to the Search Analytics API on Nov. 16. We checked which client libraries know about them yet and wrote a short script that pulls all three.

A laptop on a white desk beside printed charts, a world map and a clipboard

Key takeaways

  • On Nov. 16, 2026, Google added three options to the Search Console API: a brandedClassification dimension, a webMultimodal search type, and filterLists for several countries or devices in one request.
  • Branded data in the Search Console API only exists from Feb. 21, 2026, only for eligible top-level properties, and cannot be combined with a query filter in the same request.
  • The webMultimodal type returns traffic from Google Lens, Circle to Search on Android and image uploads in Google Search, and Google says it also reaches the BigQuery bulk export.
  • In our Nov. 16 check, the newest Google API client for Python (2.202.0) still shipped an August 2026 schema without the new fields but sent them to the API unchanged.
  • Our free Python script uses the standard library to pull a branded and non-branded split by device for any group of countries, plus Lens and Circle to Search traffic next to regular web search.

The Search Console API can now do three things that used to need the Search Console website: split traffic into branded and non-branded searches, report searches made with Google Lens and Circle to Search, and filter by a list of countries or devices in a single request. Google announced the change on its Search Central blog on November 16, 2026. It applies to every Search Console property worldwide, though branded data only appears for sites Google considers eligible.

If you pull Search Console data into Looker Studio, a spreadsheet, a BigQuery job or your own scripts, this removes two chores: maintaining a list of brand spellings in a regular expression, and sending one request per country and adding the results up. Below is what changed, the rules that will trip you up, what we found when we checked Google's own client libraries, and a short script that uses all three.

What did Google add to the Search Console API?

Three options in the Search Analytics query method, according to Google's announcement and the API reference:

  • brandedClassification: a new dimension you can group by or filter on. Rows come back as BRANDED or NON_BRANDED.
  • type: "webMultimodal": a new search type covering Google Lens, Circle to Search on Android and image uploads in Google Search. Google says the same data also flows into the BigQuery bulk data export for properties that have it turned on.
  • filterLists: a new field inside each filter group that matches a row if its country or device equals any value in a list. Google's examples are regional groups such as EMEA, LATAM or DACH.

All three were already in the Performance report on the website. The branded queries filter launched there in November 2025 and reached all eligible sites on March 11, 2026; web multimodal reporting arrived on September 24, 2026; the multi-country and multi-device filters followed later. Google says the API versions answer requests from people building custom reports and automated workflows.

How does the branded queries filter work in the API?

You add brandedClassification to dimensions to split results, or filter on it with the equals operator (the only one it supports). The API reference lists three limits worth knowing before you build a dashboard on it:

  • Data starts on February 21, 2026. Anything earlier has no branded classification, so year-over-year brand comparisons are not possible yet.
  • Only eligible properties get rows. Google's original announcement says the filter covers top-level properties only, not URL path or subdomain properties, and only sites with enough queries and impressions. For any other property the API returns no rows at all, with no error.
  • It can't be combined with a query filter in the same request. If you want "non-branded queries containing 'price'", pull the non-branded rows grouped by query and filter them yourself.

The classification is Google's own. Google says it is made by "an internal, AI-assisted system", covers the brand name in all languages, typos, and products unique to the site, and may misclassify some queries. It also says the filter has no effect on rankings. Our view: treat the split as a quick trend line, not an audit. If brand traffic matters to a decision, spot-check the queries Google put in each bucket.

Which searches count as web multimodal?

Set type to webMultimodal and the API returns searches made with an image rather than typed words: Lens, Circle to Search on Android and image uploads to Google Search. Google's September announcement also listed Chrome's right-click "Search this image". This is separate from the image type, which covers the Images tab.

For shops, restaurants, venues and anyone whose products get photographed, this is the first way to track camera searches in a scheduled report. Expect small click numbers next to regular web search on most sites; the useful signal is which pages and countries get them at all.

How do multi-country filters work?

Put a filterLists entry inside a filter group, with dimension set to country or device and a list of three-letter ISO country codes (or DESKTOP, MOBILE, TABLET) in expressions. A row matches if it equals any value in the list. Two rules from Google's documentation:

  • filterLists only accepts country and device. Pages and queries still need the older filters field.
  • One request can't filter the same dimension in both filters and filterLists.

Google's machine-readable API description (its discovery document, revision 20261115) adds a limit the reference page doesn't mention: up to 1,000 values in one list. That is more than every country code there is, so a whole region fits in one call.

This matters most for sites that sell or publish across borders. A UK company can now pull the UK and Ireland together, a German one the DACH countries, an Indian one South Asia, with one request instead of one per country added up by hand.

What we found when we checked Google's client libraries

Most people call this API through Google's client libraries rather than raw HTTP, so on November 16 we checked whether those libraries know about the new options yet.

  • Google's discovery document is current. The live description for the Search Console API (revision 20261115) includes filterLists, the BRANDED_CLASSIFICATION dimension and the WEB_MULTIMODAL type.
  • The Python library is behind but works. The newest google-api-python-client (2.202.0, released November 10) ships a bundled copy of the Search Console description from August 5, 2026, with none of the three. We built the Search Console service from that bundled copy, sent a query using all three new options through it, and captured the outgoing request: the library passed the body through unchanged. So Python users don't need to wait for an update.
  • The Node.js types are behind. In googleapis 190.0.0 for Node.js (released November 12), the TypeScript type for a filter group has filters and groupType but no filterLists, so a strict TypeScript project will flag the new field. Until Google regenerates the package, cast the request body or call the endpoint directly.

A script that pulls all three

This builds on our weekly Search Console report in Python and reuses its saved login (gsc-token.json), so follow steps 1 and 2 there first. It uses only Python's standard library. For a group of countries it prints the branded and non-branded split by device over the last 28 days of settled data, then Lens and Circle to Search traffic next to regular web search.

gsc_segments.py
"""Branded vs non-branded clicks for a group of countries, by device,
plus Lens and Circle to Search (web multimodal) next to regular web search.
Standard library only. Needs gsc-token.json (see our weekly report script)."""
import datetime as dt
import json
import sys
import urllib.parse
import urllib.request
 
TOKEN_FILE = "gsc-token.json"
API = "https://www.googleapis.com/webmasters/v3/sites/"
SITE = sys.argv[1] if len(sys.argv) > 1 else "sc-domain:example.com"
# Three-letter ISO country codes, up to 1,000 in one list. DACH as an example.
REGION = sys.argv[2].split(",") if len(sys.argv) > 2 else ["deu", "aut", "che"]
 
 
def access_token():
    """Trade the saved refresh token for a one-hour access token."""
    saved = json.load(open(TOKEN_FILE))
    body = urllib.parse.urlencode({
        "client_id": saved["client_id"],
        "client_secret": saved["client_secret"],
        "refresh_token": saved["refresh_token"],
        "grant_type": "refresh_token",
    }).encode()
    with urllib.request.urlopen("https://oauth2.googleapis.com/token", body) as res:
        return json.load(res)["access_token"]
 
 
def query(token, payload):
    url = API + urllib.parse.quote(SITE, safe="") + "/searchAnalytics/query"
    req = urllib.request.Request(url, json.dumps(payload).encode(), {
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
    })
    with urllib.request.urlopen(req) as res:
        return json.load(res).get("rows", [])
 
 
def main():
    end = dt.date.today() - dt.timedelta(days=3)  # skip days still settling
    start = end - dt.timedelta(days=27)           # 28 days
    region = [{"filterLists": [{"dimension": "country", "expressions": REGION}]}]
    base = {"startDate": str(start), "endDate": str(end),
            "dimensionFilterGroups": region, "rowLimit": 1000}
    token = access_token()
 
    print(f"{SITE}  {start} to {end}  countries: {', '.join(REGION).upper()}\n")
 
    # 1. Branded vs non-branded, split by device, in one request.
    rows = query(token, {**base, "dimensions": ["brandedClassification", "device"]})
    if not rows:
        print("No branded data: the property isn't eligible (Google limits it to\n"
              "top-level properties with enough queries and impressions).\n")
    else:
        total = sum(r["clicks"] for r in rows) or 1
        print("Brand split (web search)")
        for r in sorted(rows, key=lambda r: -r["clicks"]):
            kind, device = r["keys"]
            print(f"  {kind:<11} {device:<8} {r['clicks']:>8,.0f} clicks"
                  f"  {r['clicks'] / total:6.1%}  pos {r['position']:.1f}")
        print()
 
    # 2. Lens, Circle to Search and image uploads next to regular web search.
    print("Search type        clicks   impressions")
    for kind in ("web", "webMultimodal"):
        rows = query(token, {**base, "type": kind})
        c = rows[0]["clicks"] if rows else 0
        i = rows[0]["impressions"] if rows else 0
        print(f"  {kind:<14} {c:>8,.0f}  {i:>12,.0f}")
 
 
if __name__ == "__main__":
    main()

Run it with your property exactly as Search Console lists it, and optionally a comma-separated list of countries:

python gsc_segments.py sc-domain:example.com
python gsc_segments.py sc-domain:example.com gbr,irl
python gsc_segments.py https://www.example.com/ ind,pak,bgd,lka,npl

How we tested it: we haven't yet run it on a live property with the new data, so we tested it against a local server that checks every request against Google's discovery document and the rules on the reference page (allowed search types and dimensions, country and device only in filterLists, no more than 1,000 values, no branded grouping with a query filter). The script's three requests passed. A deliberately broken copy, with page in the filter list and a misspelled search type, failed all four of those checks, so the test does catch mistakes. The empty-response path prints the eligibility message instead of a misleading zero.

What should you change this week?

  • If your dashboards use a brand regex, add a brandedClassification version next to it for a month and compare. Keep the regex for anything before February 21, 2026, and for properties that aren't eligible.
  • If you report by region, replace the per-country loops with one filterLists request per region.
  • If people photograph what you sell, add a webMultimodal line to your monthly report so you see the trend from the start.
  • If you use the Node.js client with TypeScript, expect a type error on filterLists until the package updates.

What we don't know yet

  • Whether brandedClassification returns data together with type: "webMultimodal". Google's branded filter announcement listed web, image, video and news, and the API reference doesn't say.
  • When Google will refresh the Python library's bundled copy and the Node.js types.
  • How often branded classifications change for a given query. Google calls the system dynamic, so the same query could move between buckets over time.

Sources

Photo of Kiran Dasgupta

About the author

Kiran Dasgupta, Editor

Kiran runs Kihan Marketing, a web design, SEO and ads agency, and manages dozens of websites across real estate, home services and healthcare. He writes about SEO, AI search and paid ads news, and what it means for the people who run websites.