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.
- Node.js Environment: Make sure Node.js is installed on your system.
- Install Packages: Install the required npm packages:
bash
1npm install googleapis google-auth-library - 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_emailandprivate_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.
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.
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.
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.
-
Assuming Universal Availability for Brand Data: The
brandedClassificationdata 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 thebrandedClassificationfield 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. -
Ignoring Pagination for Large Datasets: The Search Analytics API imposes limits on the number of rows returned per request, often thousands. When using
filterListsto broaden your query across multiple countries or devices, you are more likely to exceed this limit. Always implement pagination logic using thestartIndexparameter to retrieve the full dataset. This involves making successive API calls, incrementingstartIndexby therowLimituntil no more data is returned. Neglecting pagination will result in incomplete data and skewed analysis. -
Mixing Filter Types Incorrectly: While
filterListsis powerful for grouping multiple values of the same dimension (e.g., multiple countries), it's crucial to understand its scope. It is specifically designed forcountryanddevicedimensions. For other dimensions, you should continue to use the standardfilterparameter. Furthermore, ensure that the dimensions you are filtering by are compatible with thedimensionsyou are requesting. For example, filtering bycountrybut only requestingqueryas a dimension will still work, but you won't be able to see the country breakdown in the output. Yourdimensionsarray must include the fields you need for analysis. -
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.
-
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
brandedClassificationdimension usage and ensure your property is qualified. -
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 usingfilterLists. This helps confirm thatfilterListsis correctly aggregating data across your specified regions. -
Validate Multimodal Query Types: When retrieving
webMultimodalresults, 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,webMultimodaltype, andfilterListsfor multi-country/device filtering, aligning more closely with the Search Console UI. - Efficiency Gains: Utilizing
filterListssignificantly 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 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.


