Advertisement
Content Moved? Use Search to Locate
Two business professionals reviewing graphs and data on a tablet and paper report indoors.

How to Use Google’s New Search Analytics API Filters

To use Google’s new Search Analytics API options safely, test each request with a fixed date range, confirm the returned dimensions and filter values, and compare it only with a compatible Search Console Performance report view. Google announced the additions on November 16, 2026, as API request capabilities—not a general change to how every Search Console report works. Branded classification also has eligibility and filter restrictions, and API results are not guaranteed to include every data row. See Google’s New Filtering and Reporting Capabilities in the Search Analytics API.

What changed in the Search Analytics API

Google announced three additions: branded-query classification, the webMultimodal search type, and multi-value country and device filtering. The Search Analytics API: Query Reference, marked updated November 16, 2026, documents the current request fields and constraints. Treat these as options for building API reports; don’t assume they change the available dimensions or totals in every Search Console interface view.

The webMultimodal type covers Google Lens, Circle to Search on Android, and image uploads in Google Search. It is distinct from the default web type. Keep it as its own search-type selection in reports rather than folding its results into web or describing it as all image-related Google Search activity. The API’s filterLists option lets a request match a country or device against any of the listed values. That is a multi-value filter, not a new reporting dimension, as described in the API reference.

Build a representative multi-value request

Start with one question your report needs to answer. The following hypothetical request plan asks for daily webMultimodal data across two markets, while keeping device as a returned dimension:

startDate: 2026-10-01
endDate: 2026-10-28
type: webMultimodal
dimensions: [date, device]
filterLists: country matches any of [usa, can]

This is a field-level sketch, not a complete copy-and-paste request body; use the request structure in Google’s Search Analytics API: Query Reference when serializing the fields. Country values use three-letter codes. Device values, when you filter by device instead, are DESKTOP, MOBILE, or TABLET. Listed values are alternatives matched by equality: the example includes rows for either requested country. Do not also filter country in filters in the same request; the API does not allow the same dimension to be filtered in both filters and filterLists.

Choose dimensions to control how the response is broken out. With date and device in the example, the output is split by those dimensions; because country is filtered but not selected as a dimension, the market results form a combined USA-and-Canada segment. Label that segment clearly. If you need country-level rows, include country as a dimension and validate that the returned keys contain it.

Request branded classification separately

The API reference lists BRANDED and NON_BRANDED as branded-classification values. Google documents availability only for top-level properties with sufficient query and impression volume; it does not publish a guaranteed eligibility threshold. The reference says this data is available starting February 21, 2026. That is the data-availability date, not the November 16 announcement date.

For a branded test, add the branded-classification condition using the equals operator and one of the documented values. Do not combine it with a query filter in the same request. If you also need query-level data, test that as a separate request without branded classification. An empty branded response alone does not establish that Google has restricted the property: check whether it is a top-level property, the selected date range, and the request setup. Because Google does not document a guaranteed volume threshold, you cannot use a published numeric cutoff to determine eligibility.

Test the response before rolling it into a report

  1. Confirm the property and data scope. Verify the property you query in Search Console. For branded classification, confirm it is a top-level property and account for the documented query- and impression-volume eligibility condition. Use a date range that includes the data you intend to report.
  2. Write down the request. Record the start and end dates, search type, selected dimensions, filters, and aggregation choice. Keep the branded-classification test separate from any request that filters by query.
  3. Run a small, representative test. Use the same request settings you expect to automate. Inspect the response keys, the country or device values returned, and the number of rows—not just the click or impression totals.
  4. Check the expected shape. Confirm that requested key dimensions appear and that country or device values are limited to those requested. If you requested a combined market segment by filtering country without selecting it as a dimension, make sure the report labels it as combined rather than presenting it as a country breakdown.
  5. Compare like with like. In the Performance report, align the date range and search type, and use compatible dimensions and aggregation. Record which view you compared so a later report change can be traced to its settings.

If the response is empty or partial, check property eligibility, date range, filters, and request dimensions before interpreting it as a performance change. The Search Analytics API sorts results by clicks and is subject to internal Search Console limits; Google does not guarantee that every data row will be returned, as the API reference explains. For interface comparisons, Google’s Performance Report (Search Results)—Overview and Basic Setup explains that data is grouped by selected dimensions and search type, and that chart and table totals can differ because of aggregation—for example, property-level versus page-level aggregation. Exact API-to-interface total parity is not promised.

Roll out with a clear reporting label

Hypothetical ecommerce example: A store wants one daily view of multimodal search activity across the United States and Canada, split by device. A single country multi-value filter can request that combined market slice instead of making separate country requests. Label the result “USA + Canada combined,” retain device as a dimension, and do not compare it with a single-country report or a view using a different aggregation level. If the business needs to compare the two markets, include country as a dimension and test that response separately.

Before production rollout, save the request settings alongside the report definition, confirm the returned keys and row shape over the fixed test period, and monitor row counts as well as reported metrics. If you need help implementing and maintaining a Search Console reporting workflow, Splinternet’s SEO services can help configure the reporting, validate what it measures, and keep the setup under review.

Sources

Editorial note: AI assists with research, drafting and automated checks. Sources are linked so you can verify the guidance. Platform requirements can change; confirm the details that apply to your setup.