🚀Publish FREEJoin WriterDock's early community of writers.Start Writing — It's Free

Google Search Console API: Enhanced Filtering for SEO

Suraj Kumar

Suraj Kumar

Founding Writer #1Contributor

November 21, 2026•12 min read•3 views

Illustration for "Google Search Console API: Enhanced Filtering for SEO"

The Google Search Console API has long been a critical tool for developers and marketers automating performance tracking. Historically, extracting granular data often required complex workarounds or extensive post-processing. Google Search Central recently announced significant new filtering and reporting capabilities in the Search Analytics API, designed to bring its functionality closer to the Search Console user interface. This guide explains these updates, their importance for SEO reporting, and practical steps to integrate these new parameters into your existing data pipelines.

What's New in the Search Analytics API

According to Google Search Central, the update introduces three specific capabilities to the API that were previously available only within the Search Console interface. These enhancements directly address common challenges faced by site owners, international businesses, and creators of third-party SEO tools.

The first key addition is support for branded queries. You can now group or filter your data by brandedClassification to easily compare performance between branded and non-branded traffic. This feature eliminates the need to manually maintain complex regular expression lists of your brand names, product names, and their variations, streamlining data segmentation.

The second new feature enables Web Multimodal reporting. By setting the type parameter to webMultimodal, you can retrieve performance data specifically for Google Lens, "Circle to Search" on Android, and image uploads in Google Search. This data is also available in BigQuery for properties with active bulk data exports, facilitating more in-depth, offline analysis of visual search trends.

The third and arguably most impactful operational improvement is the introduction of multiple country and device filters via the filterLists field. Previously, analyzing performance across a specific region (such as EMEA) and a particular device type (like mobile) typically involved making multiple separate API requests or filtering a large dataset on the client side. The new filterLists field allows you to specify multiple countries or devices within a single API call, significantly improving efficiency.

Why These Updates Matter for SEO Reporting

For developers building SEO tools, internal dashboards, or custom reporting solutions, these changes offer substantial benefits, primarily by reducing API quota consumption and simplifying code complexity.

Enhanced Efficiency in Multi-Region Analysis

International websites frequently need to segment performance data by geographic region. Before this update, analyzing performance for a region like "EMEA" (Europe, Middle East, and Africa) required identifying every country code within that region and then either executing numerous individual API requests or processing a massive dataset after a broad query. With filterLists, you can now pass a group of country codes in a single request. This is particularly valuable for monitoring brand growth in specific regional hubs, such as DACH (Germany, Austria, Switzerland) or LATAM (Latin America), allowing for more focused and efficient data retrieval.

Automated Brand vs. Non-Brand Segmentation

Manually managing lists of brand keywords for segmentation is a tedious and error-prone process. If a new product launches or a brand undergoes a rebrand, these manual lists quickly become outdated. The brandedClassification parameter leverages Google’s own classification logic, ensuring that your data is segmented accurately and consistently without requiring ongoing manual maintenance. It's important to note that this data is only available for qualified properties. For properties that do not meet Google's qualification criteria, the API response will not include these specific rows, necessitating robust parsing logic to handle potentially empty or missing data gracefully.

Tracking Multimodal Search Trends

User search behavior is continually evolving, with an increasing reliance on visual and interactive search methods. Integrating webMultimodal data provides crucial insights into how your site performs in these emerging search verticals. This is vital for marketers who need to understand if their visual content, such as product images or infographics, is effectively driving traffic from new sources beyond traditional text-based organic clicks. By monitoring multimodal performance, you can identify opportunities to optimize visual assets and content strategies for these growing search channels.

Prerequisites and Setup

Before you can implement the new filters, ensure you have the necessary environment set up. The following examples are for Node.js, using the Google APIs Client Library.

  1. Node.js Environment: Make sure Node.js is installed on your system.
  2. Install Packages: Install the required npm packages:
    bash
    1npm install googleapis google-auth-library
  3. Service Account Credentials: The most secure and recommended way to access the Search Console API for automated tasks is via a service account.
    • Go to the Google Cloud Console.
    • Create a new project or select an existing one.
    • Navigate to "APIs & Services" > "Credentials".
    • Create a new Service Account Key. Download the JSON file containing your client_email and private_key.
    • Grant the service account "Owner" or "User" permissions in Google Search Console for the specific property you intend to query. This is done by adding the service account's email address (from the JSON file) as a user in Search Console.

How to Implement the New Filters

The following code snippets illustrate how to structure your API requests using the new parameters. Remember to replace placeholder values like your-service-account-email, your-private-key, sc-domain:example.com, and the date ranges with your actual credentials and desired query parameters.

Filtering by Branded Classification

To segment your traffic into branded and non-branded categories, include brandedClassification as a dimension in your API request.

javascript
1const { google } = require('googleapis');
2const path = require('path');
3
4async function fetchBrandedData() {
5  // Load service account key from a file or environment variables
6  // For security, avoid hardcoding credentials directly in code.
7  // Example: const key = require('./path/to/your-service-account-key.json');
8  // Or use environment variables for production.
9  const auth = new google.auth.JWT(
10    'your-service-account-email@your-project-id.iam.gserviceaccount.com', // Replace with your service account email
11    null, // Path to key file (can be null if private_key is provided directly)
12    '-----BEGIN PRIVATE KEY-----\nYOUR_PRIVATE_KEY_HERE\n-----END PRIVATE KEY-----\n', // Replace with your private key
13    ['https://www.googleapis.com/auth/webmasters.readonly']
14  );
15  const searchconsole = google.searchconsole({ version: 'v1', auth });
16
17  try {
18    const res = await searchconsole.searchanalytics.query({
19      siteUrl: 'sc-domain:example.com', // Replace with your property URL
20      startDate: 'YYYY-MM-DD', // Replace with desired start date
21      endDate: 'YYYY-MM-DD',   // Replace with desired end date
22      dimensions: ['query', 'brandedClassification'],
23      rowLimit: 100 // Use rowLimit instead of limit for clarity
24    });
25
26    console.log('Branded Data Rows:', res.data.rows);
27    // Each row will contain 'brandedClassification' as 'branded' or 'non-branded'
28  } catch (error) {
29    console.error('Error fetching branded data:', error.message);
30  }
31}
32
33fetchBrandedData();

Using filterLists for Multi-Country and Device Analysis

The filterLists parameter enables you to specify multiple values for a single dimension, making it more efficient than chaining multiple individual filter parameters for the same dimension.

javascript
1const { google } = require('googleapis');
2const path = require('path');
3
4async function fetchRegionalMobileData() {
5  const auth = new google.auth.JWT(
6    'your-service-account-email@your-project-id.iam.gserviceaccount.com', // Replace with your service account email
7    null,
8    '-----BEGIN PRIVATE KEY-----\nYOUR_PRIVATE_KEY_HERE\n-----END PRIVATE KEY-----\n', // Replace with your private key
9    ['https://www.googleapis.com/auth/webmasters.readonly']
10  );
11  const searchconsole = google.searchconsole({ version: 'v1', auth });
12
13  try {
14    const res = await searchconsole.searchanalytics.query({
15      siteUrl: 'sc-domain:example.com', // Replace with your property URL
16      startDate: 'YYYY-MM-DD', // Replace with desired start date
17      endDate: 'YYYY-MM-DD',   // Replace with desired end date
18      dimensions: ['country', 'device'],
19      filterLists: [
20        {
21          dimension: 'country',
22          groupValue: {
23            values: ['DE', 'FR', 'ES', 'IT'] // Example: Countries in Europe
24          }
25        },
26        {
27          dimension: 'device',
28          groupValue: {
29            values: ['mobile', 'tablet'] // Example: Mobile and tablet devices
30          }
31        }
32      ],
33      rowLimit: 1000
34    });
35
36    console.log('Regional Mobile Data Rows:', res.data.rows);
37    // Each row will show data for the specified country and device combinations
38  } catch (error) {
39    console.error('Error fetching regional mobile data:', error.message);
40  }
41}
42
43fetchRegionalMobileData();

Retrieving Web Multimodal Data

To obtain performance data specifically for Google Lens, Circle to Search, and image uploads, set the type parameter to webMultimodal.

javascript
1const { google } = require('googleapis');
2const path = require('path');
3
4async function fetchMultimodalData() {
5  const auth = new google.auth.JWT(
6    'your-service-account-email@your-project-id.iam.gserviceaccount.com', // Replace with your service account email
7    null,
8    '-----BEGIN PRIVATE KEY-----\nYOUR_PRIVATE_KEY_HERE\n-----END PRIVATE KEY-----\n', // Replace with your private key
9    ['https://www.googleapis.com/auth/webmasters.readonly']
10  );
11  const searchconsole = google.searchconsole({ version: 'v1', auth });
12
13  try {
14    const res = await searchconsole.searchanalytics.query({
15      siteUrl: 'sc-domain:example.com', // Replace with your property URL
16      startDate: 'YYYY-MM-DD', // Replace with desired start date
17      endDate: 'YYYY-MM-DD',   // Replace with desired end date
18      type: 'webMultimodal', // Key change for multimodal data
19      dimensions: ['query', 'page'], // Common dimensions for multimodal analysis
20      rowLimit: 100
21    });
22
23    console.log('Web Multimodal Data Rows:', res.data.rows);
24    // This will show queries and pages performing in multimodal search
25  } catch (error) {
26    console.error('Error fetching multimodal data:', error.message);
27  }
28}
29
30fetchMultimodalData();

Common Mistakes and Pitfalls

Even with these improved API capabilities, implementation errors can lead to missing or incorrect data. Understanding these common pitfalls can save significant debugging time.

  1. Assuming Universal Availability for Brand Data: The brandedClassification data is not available for all properties. Google qualifies properties based on various factors, including traffic volume and historical data. If your property is not qualified, the API will not return rows for this dimension, or the brandedClassification field might be absent. Your code must anticipate this by checking for the presence of this dimension in the response schema or by gracefully handling empty datasets without throwing errors. Failing to do so can lead to incomplete reports or application crashes.

  2. Ignoring Pagination for Large Datasets: The Search Analytics API imposes limits on the number of rows returned per request, often thousands. When using filterLists to broaden your query across multiple countries or devices, you are more likely to exceed this limit. Always implement pagination logic using the startIndex parameter to retrieve the full dataset. This involves making successive API calls, incrementing startIndex by the rowLimit until no more data is returned. Neglecting pagination will result in incomplete data and skewed analysis.

  3. Mixing Filter Types Incorrectly: While filterLists is powerful for grouping multiple values of the same dimension (e.g., multiple countries), it's crucial to understand its scope. It is specifically designed for country and device dimensions. For other dimensions, you should continue to use the standard filter parameter. Furthermore, ensure that the dimensions you are filtering by are compatible with the dimensions you are requesting. For example, filtering by country but only requesting query as a dimension will still work, but you won't be able to see the country breakdown in the output. Your dimensions array must include the fields you need for analysis.

  4. Neglecting BigQuery for Very Large Volumes: For extensive historical analysis or processing extremely large datasets, relying solely on the API can be slower and more prone to hitting quota limits. Google Search Central explicitly states that Web Multimodal data is available in BigQuery for properties with active bulk data exports. If your workflow involves long-term trend analysis, processing petabytes of data, or combining Search Console data with other data sources, consider routing these heavy queries to BigQuery. Use the API primarily for real-time dashboards, smaller ad-hoc queries, or lightweight monitoring tasks.

Verifying Your Implementation

After updating your code to use the new API features, it's essential to verify the results against the Search Console UI to ensure accuracy and consistency.

  1. Sanity Check Brand Data: Compare the total clicks reported for "branded" queries in your API response against the "Branded" filter in the Search Console UI's Performance report. The numbers should match closely, allowing for minor data latency differences. If there's a significant discrepancy, double-check your brandedClassification dimension usage and ensure your property is qualified.

  2. Test Multi-Region Summation: If you filter for multiple countries using filterLists (e.g., DE, FR, ES, IT), retrieve the data for each country individually as well. Sum the clicks for these individual countries in your data warehouse or spreadsheet. This sum should approximately equal the total clicks returned when filtering for the entire group using filterLists. This helps confirm that filterLists is correctly aggregating data across your specified regions.

  3. Validate Multimodal Query Types: When retrieving webMultimodal results, examine the types of queries returned. These queries should primarily be visually or interactively driven (e.g., image descriptions, product searches via Lens). If you observe a significant number of standard text-based queries, it might indicate an issue with how you're interpreting the data, or it could highlight a property with a particularly high volume of multimodal traffic that also includes text components. Cross-reference with the Search Console UI's "Search appearance" filter for "Web Multimodal" to ensure alignment.

Key Takeaways

  • New Filtering Options: The Search Analytics API now supports brandedClassification, webMultimodal type, and filterLists for multi-country/device filtering, aligning more closely with the Search Console UI.
  • Efficiency Gains: Utilizing filterLists significantly reduces the need for multiple API calls or complex client-side filtering, leading to savings in API quota and processing time.
  • Brand Data Caveat: Branded classification data is available only for qualified properties. Implement robust error handling for properties where this data might be absent.
  • Multimodal Insights: You can now track performance from Google Lens, Circle to Search, and image uploads, providing crucial visibility into non-text search trends and user behavior.
  • BigQuery Integration: For large-scale historical analysis and extensive data processing, especially for multimodal data, leverage BigQuery if you have bulk data exports enabled, reserving the API for more immediate or smaller-scale needs.

FAQ

Is the new filtering available for all Search Console properties? The brandedClassification filter is only available for qualified properties. For other properties, the API response will not include rows for this dimension. The filterLists and webMultimodal features are generally available, but multimodal data availability depends on the property's traffic profile and the presence of such search types.

Can I use filterLists with any dimension? No, filterLists is specifically designed for filtering by multiple countries or devices in a single request. For other dimensions, you should continue to use the standard filter parameter. Always consult the official API documentation for compatible values and combinations to ensure correct usage.

How does webMultimodal data differ from standard search data? Standard search data primarily covers text-based queries and traditional organic search results. webMultimodal data, in contrast, covers queries initiated through visual or interactive methods, such as image uploads, Google Lens, or Circle to Search. This distinction allows you to analyze how users discover your site through these distinct, non-textual search pathways.

Do I need to update my BigQuery schema for these changes? If you are exporting data to BigQuery, Google Search Central notes that multimodal data is available for properties with active bulk data exports. While the system typically handles schema updates for new fields automatically, it's prudent to review your BigQuery tables and export configurations to ensure that any new columns related to brandedClassification or multimodal metrics are being correctly captured and processed in your data warehouse.

About the Author

Suraj Kumar

Suraj Kumar

@surajkumar

Founding Writer #1Contributor

Suraj Kumar is a writer, entrepreneur, and the CEO and founder of this website, sharing simple and practical insights on business, creativity, and personal growth. With experience building digital projects, they enjoy helping others learn, grow, and succeed online.

Read Next

More articles you might enjoy

View all articles
3