Metrics
This Extension requires a Pro license
Current version: 1.5.1
SearchWP Metrics is a premium extension that tracks and analyzes searches performed on your website. It provides detailed insights into what visitors are searching for, which results they click, and how your content performs in search results.
By analyzing search activity, Metrics helps you make informed decisions about improving your content, optimizing search relevance, and identifying gaps in your site’s information.
This extension is especially useful for high-traffic blogs, documentation sites, and WooCommerce stores, where understanding visitor search behavior can help improve user experience and increase conversions.
Table of Contents
Installation & Overview
Metrics was built to be a turnkey Extension for SearchWP. It is a standalone WordPress plugin that should be installed and activated alongside SearchWP itself. Once installed and activated, Metrics automatically integrates with WordPress’s default search form to record all user search queries and track search result interactions.
In addition to the default search form, Metrics also integrates with SearchWP custom Search Forms and includes click tracking for SearchWP templates, ensuring comprehensive data collection across all search implementations on your site.
To access your search analytics, navigate to SearchWP → Metrics menu link. This opens the Metrics dashboard, where you can review all collected search data and insights.
Important Note: Metrics supersedes SearchWP’s core Statistics feature. When Metrics is active, the SearchWP Statistics page and Dashboard Widget will no longer display. Instead, enhanced counterparts from Metrics will take their place, providing more detailed analytics and advanced features.
Data Display Controls
The Metrics dashboard provides flexible controls for filtering and viewing your search data. These controls allow you to focus on specific time periods, search terms, and engines to gain targeted insights.
Date Range: The date range selector allows you to view search activity for a specific period. By default, Metrics displays data from the last 30 days, but you can select any custom date range to analyze historical or recent search activity.
Search Query Controls: The search query controls allow you to filter the displayed metrics data to specific search terms. This feature is useful for analyzing performance of particular keywords or topics. Additionally, you can add search terms to an ignored list directly from this control panel. Ignored searches are excluded from all metrics reports, helping you filter out irrelevant or spam queries from your analytics.
Engines to Display: If your site uses multiple SearchWP engines, you can choose which engines should be included in the displayed metrics. By default, all SearchWP engines on your site are selected. This allows you to review search behavior for specific areas of your site
Reviewing Data
The Metrics dashboard organizes search data into several sections, each providing unique insights into how visitors interact with your site’s search functionality.
Graphical Chart
Below the data display controls, a graphical chart visualizes the top searches performed on your site each day for the selected date range period. This chart displays data for all engines selected in the display controls, providing a visual representation of search trends and patterns over time. This makes it easy to identify spikes in search activity, trending topics, and changes in user behavior.lected engine. Below are details for each engine that provide specific metrics for further examination:
Engine Statistics
The Engine Statistics section provides detailed quantitative information about search performance for the selected date range period.
Total Searches: Displays the total number of searches performed by all users during the selected period, giving you a sense of overall search activity volume.No Result Searches: Shows the total count of searches that returned zero results.
Clicking the icon next to this metric reveals a detailed list of all search queries that failed to return results, along with how many times each query was attempted. This list is invaluable for identifying content gaps and opportunities for new content creation. You can review this list for accuracy over time, and clicking the × icon next to any failed search query will add it to your ignored searches list.
Total Results Viewed: Indicates the total number of search result pages that were viewed by users on your site, helping you understand how deeply users browse through search results.
Searches Per User: Displays the average number of searches performed per user, providing insight into how extensively visitors use your search functionality.
Clicks Per Search: Shows the average number of result clicks per search query, indicating how effectively your search results match user intent.
Average Click Rank: Reveals the average position of clicked results in the search results list, helping you understand whether users typically find what they need at the top of results or must browse deeper.
Popular Searches
This section displays a ranked list of the most frequently performed searches for the selected date range period. Each entry shows the search query term and the total number of times that term was searched. By default, the list displays the top 10 searches performed on your site.
Clicking on any listed popular search or the “View More” button reveals additional details, including which specific posts or pages were clicked as a result of that search query and how many times each result was clicked. This granular data helps you understand not just what users are searching for, but which content successfully satisfies those search queries.
The View More interface also provides options to view additional query terms beyond the top ten and export the data to a CSV file for further analysis.
Insights
The Insights section provides intelligent analysis and actionable recommendations based on your search data. Metrics doesn’t just collect search data—it implements sophisticated analysis to identify opportunities for content improvement.
By analyzing conversion rates, popular searches, search frequency, and result ranking positions, Metrics can identify situations where:
- Content is ranking low but getting a lot of clicks: can this content be optimized to rank higher?
- Content is getting a high conversion rate: should this content be more prominently linked because so many visitors are searching for it?
- Searches are converting on a variety of posts: should new content be created for these search queries?
Insights can call out some areas of improvement based on actual visitor searches:
Exporting Data
Within each engine details section, you can export any of the displayed data for the selected date period. This functionality allows you to perform deeper analysis, create custom reports, or share search analytics with stakeholders.
Available export options include:
Export Searches Over Time: Downloads time-series data showing search volume trends across the selected period.
Export Engine Statistics: Exports all statistical metrics for the selected engine and date range.
Export Popular Searches: Downloads the complete list of popular search terms with their frequency counts.
All exports are formatted as CSV files, which can be opened in spreadsheet applications like Microsoft Excel or Google Sheets for further analysis, visualization, or reporting.
General Settings
The Metrics General Settings page provides configuration options for data management, privacy controls, and advanced features.
Clear Metrics Data: This option permanently deletes all data from the Metrics tables in your database, providing a complete reset of your search analytics.
Clear Data Before: Allows you to specify a date and delete all metrics data collected before that date, useful for removing outdated information while preserving recent analytics.
Clear Data at Intervals: Enables automatic data deletion using background processes at regular intervals. Available options include one month, three months, six months, one year, or custom intervals.
Remove All Ignored Searches: Clears the list of search terms you’ve marked to ignore, allowing them to appear in reports again if needed.
Logging Rules
Metrics provides controls to exclude certain searches from being recorded, helping you maintain clean, relevant data by filtering out internal searches and automated traffic.
You can specify any combination of WordPress User IDs or Roles that should have their searches ignored. For example, adding the “administrator” role ensures that admin searches don’t pollute your visitor analytics. You can also maintain a list of IP addresses to blacklist, making it easier to exclude searches from your office network, development environments, or known bot traffic sources.
Advanced Options
Influence Search Results Using Click Data: When enabled, this option uses click tracking data to influence the ranking of search results over time. Results that receive more clicks will gradually rank higher than those with fewer clicks, creating a self-improving search algorithm based on actual user preferences and behavior.
Remove All Metrics Data on Uninstallation: With this checkbox enabled, Metrics will remove all custom database tables, click tracking data, and stored options when the plugin is deleted. This ensures a complete cleanup if you decide to stop using Metrics.
View Background Processes: When enabled, displays a status bar showing the progress of automatic data deletion jobs and other background tasks.
Click Tracking
By default, Metrics will automatically track clicks for the Default engine, assuming that your search results template uses The Loop. Any link within The Loop that is generated using get_permalink() (or variant thereof) will automatically be set up for click tracking. If you’re using a standard search results template you should be all set without needing to make any edits.
To integrate click tracking in your supplemental engine(s) you need to add two Hooks to your results template, one before your own loop of results, and one afterward.
Begin Metrics link tracking:
Stop tracking links:
All links generated with get_permalink() (or variant thereof) within those two actions will be processed by the click tracking within Metrics.
Dashboard Widget
Metrics ships with its own Dashboard Widget that allows you to take a quick look at basic data when you log in to your site.
The Widget updates in real time as you visit your Dashboard, and you can customize the number of popular searches and number of popular posts shown.
Troubleshooting Common Issues
- Spam or abstract searches showing in Popular Section
SearchWP Metrics records all searches performed using the WordPress search parameter (‘s; parameter) or SearchWP forms. This includes searches that may be triggered by automated traffic, bots, crawlers from search engines like Google, or AI-related services that scan public pages. As a result, bot activity can appear in your Statistics or Metrics dashboard.
SearchWP does not include built-in bot protection to prevent automated searches. To block or limit bot activity at the server level, work with your hosting provider or server support team to implement appropriate security measures or bot filtering rules.
As an intermediate solution, you can ignore unwanted search queries directly from the Metrics interface. Navigate to Metrics Search Query Controls, click “Ignore,” and add the search terms you want to exclude from reports. Please note that ignoring a search term only removes it from your analytics reports—it does not prevent the search itself from occurring on your site or being logged in the database.
- Searches not being recorded in Metrics dashboard
By default, the Metrics dashboard displays only the top 10 most popular searches for the selected date range. To verify whether searches are being recorded, set the date range to “yesterday and today.” This will display the most recent searches in the Popular Searches section.
If searches still aren’t appearing after adjusting the date range, ensure that your search forms are using either the default WordPress search or SearchWP forms, as searches from third-party search plugins may not be tracked. If you’ve confirmed these settings and searches still aren’t being recorded, please open a support ticket from your SearchWP account so our team can investigate the issue.
- Metrics data table size grows very large in database
SearchWP Metrics records all searches performed on your site, including searches by bots and automated traffic. On high-traffic sites or sites experiencing bot activity, this can cause Metrics database tables to grow very large, potentially impacting site performance if your server has limited resources.
To optimize performance and manage database size, use the “Clear Data Before” option in Metrics settings to remove old data from a specific period that you no longer need for analysis. After clearing historical data, set up automatic data deletion using the “Clear Data at Intervals” setting. For example, configuring a 30-day or 3-month interval will periodically delete outdated search data using background processes, keeping your database size manageable while maintaining recent analytics.
- Issues due to Metrics cookie for click tracking
The SearchWP Metrics extension uses swpmtx and swpmtxnonce query parameters and cookies for click tracking on search results. On some server configurations, particularly those with aggressive caching or security policies, setting these cookies can interfere with caching services or cause 503 errors on certain pages.
If you experience conflicts with your caching configuration or errors related to the Metrics cookie, you can disable click tracking functionality using the following custom code:
Note that disabling click tracking will prevent Metrics from collecting data about which search results users click on, which will limit the insights available in the Insights section and disable the “Influence search results using click data” feature.
Filters
There are a couple of filters to note when using Metrics:
searchwp_metrics_dashboard_widget_max_popular_posts Set the number of popular posts to show in the Dashboard Widget. Default is 5, to customize:
| <?php | |
| // Show 10 popular posts in the Metrics Dashboard Widget | |
| add_filter( 'searchwp_metrics_dashboard_widget_max_popular_posts', function( $limit ) { | |
| return 10; | |
| } ); |
searchwp_metrics_dashboard_widget_max_popular_searches Set the number of searches to show in the Dashboard Widget. Default is 5, to customize:
| <?php | |
| // Show 10 popular searches in the Metrics Dashboard Widget | |
| add_filter( 'searchwp_metrics_dashboard_widget_max_popular_searches', function( $limit ) { | |
| return 10; | |
| } ); |
searchwp_metrics_click_param Customize the URL parameter used for click tracking. Default is swpmtx, to customize:
| <?php | |
| // Customize the search parameter used by click tracking in Metrics | |
| add_filter( 'searchwp_metrics_click_param', function( $param ) { | |
| return 'myparam'; | |
| }); |
searchwp_metrics_redirect_tracking Control whether Metrics redirects away from the tracking URL once a click has been tracked. Default is true, to customize:
| <?php | |
| // Prevent Metrics from redirecting away from click tracking URL | |
| add_filter( 'searchwp_metrics_redirect_tracking', '__return_false' ); |
searchwp_metrics_normalize_logged_searches Control whether Metrics normalizes search queries before logging them. Default is true, to customize:
| <?php | |
| // Prevent Metrics from normalizing queries before logging | |
| add_filter( 'searchwp_metrics_normalize_logged_searches', '__return_false' ); |
searchwp_metrics_capability Customize the capability required to view Metrics data. Default is publish_posts, to customize:
| <?php | |
| // Limit Metrics data to those who can manage_options | |
| add_filter( 'searchwp_metrics_capability', function( $capability ) { | |
| return 'manage_options'; | |
| }); |
searchwp_metrics_override_stats Control whether Metrics overrides SearchWP’s core statistics. Default is true, to customize:
| <?php | |
| add_filter( 'searchwp_metrics_override_stats', '__return_false' ); |
searchwp_metrics_click_buoy Control whether Metrics applies its data to the search algorithm. This can also be controlled in the settings. Default is false, to customize:
| <?php | |
| // Tell Metrics to influence search results by giving weight to posts with a higher conversion rate | |
| add_filter( 'searchwp_metrics_click_buoy', '__return_true' ); |
searchwp_metrics_skip_uid Metrics uses anonymous IDs to track clicks. Use this hook to prevent the generation of these IDs. Default is false, to customize:
| <?php | |
| // Prevent UID generation in Metrics | |
| add_filter( 'searchwp_metrics_skip_uid', '__return_true' ); |
searchwp_metrics_cookie_name Control the cookie name used by Metrics to track clicks. Default is swpext86386, to customize:
| <?php | |
| // Customize the cookie name used by Metrics | |
| add_filter( 'searchwp_metrics_cookie_name', function( $name ) { | |
| return 'clicky24'; | |
| }); |
searchwp_metrics_uid_expiration Control the duration of the cookie (i.e. define the click tracking session length). Default is time() + WEEK_IN_SECONDS, to customize:
| <?php | |
| // Tell Metrics to consider a session length to be one day | |
| add_filter( 'searchwp_metrics_uid_expiration', function( $length ) { | |
| return time() + DAY_IN_SECONDS | |
| }); |
searchwp_admin_bar Control whether Metrics displays its Admin Bar entry. Default is true, to customize:
| <?php | |
| // Prevent Metrics Admin Bar entry | |
| add_filter( 'searchwp_admin_bar', '__return_false' ); |
searchwp_metrics_log_search Control whether Metrics logs this search. Default is true, to customize:
| <?php | |
| // Customize whether Metrics logs this search | |
| add_filter( 'searchwp_metrics_log_search', function( $log, $engine, $query, $hits ) { | |
| // $log is whether or not to log the search | |
| // $engine is the engine being used for the search | |
| // $query is the search query | |
| // $hits is the number of results found for this search | |
| return $log; | |
| }, 10, 4 ); |
searchwp_metrics_prevent_core_stats_log Control whether SearchWP’s core statistics feature logs this search. Default is false, to customize:
| <?php | |
| // Prevent logging in core SearchWP's core statistics when Metrics is running | |
| add_filter( 'searchwp_metrics_prevent_core_stats_log', '__return_true' ); |
searchwp_metrics_default_start_date Control the default start date (as a strtotime()-compatible string) when viewing Metrics. Default is '30 days ago', to customize:
| <?php | |
| // Have the default start date for Metrics be one week ago | |
| add_filter( 'searchwp_metrics_default_start_date', function( $start ) { | |
| return '7 days ago'; | |
| }); |
searchwp_metrics_default_end_date Control the default end date (as a strtotime()-compatible string) when viewing Metrics. Default is 'now', to customize:
| <?php | |
| // Have the default end date for Metrics be one week ago | |
| add_filter( 'searchwp_metrics_default_end_date', function( $start ) { | |
| return '7 days ago'; | |
| }); |
searchwp_metrics_first_day_of_week Control the first day of the week when viewing the date picker in Metrics. Default is 0, to customize:
| <?php | |
| // Customize the date picker in Metrics to have weeks start on Monday (zero-based index) | |
| add_filter( 'searchwp_metrics_first_day_of_week', function( $start ) { | |
| return 1; | |
| }); |
Changelog
1.5.1
- [Fix] Click-buoy post-meta deletion failing in some cases.
- [Fix] The reload button for the Popular Search Details causes the reload count field to be emptied.
1.5.0
- [New] New background process to delete Metrics data
- [Changed] The application menu is now accessible even while the Metrics data is being loaded
- [Improved] Limit Metrics cookie to HTTP requests
- [Fix] IP Addresses on Logging Rules settings not saving if multiple IPs are present
1.4.9
- [Fix] Fixes a PHP error if $_SERVER['REMOTE_ADDR'] is not set
- [Fix] Fixes a PHP notice when loading text domain since WP 6.7+
1.4.8
- [Improvement] Only check for the existence of DB tables on activation
- [Changed] Metrics UID cookie is now set at page load instead of after search query
- [Fix] PHP warning if there are no SearchWP engines
1.4.7
- [New] Added automatic click tracking to SearchWP Live Ajax Search results.
- [Improvement] Minor UI improvements
- [Improvement] Minified CSS assets
- [Fix] Click tracking working only on first page of results
1.4.6
- [Fix] Regression in the previous release that caused a MySQL error on initial table creation
1.4.5
- [New] New option to automatically delete Metrics data older than a specified interval
- [Improvement] Metrics data in the administration area is loaded incrementally to avoid server timeouts
- [Improvement] New date picker with preset date ranges
- [Improvement] Reduced Metric values to only two digits after the decimal point, for improved readability
- [Improvement] Various UX improvements on some controls and modal panels
- [Improvement] Reduced assets file size
- [Notice] This release removes the Metrics metadata table. If you would like to retain this data: BACK UP the existing table before updating
1.4.4
- [Fix] Malformed Blocklist causes PHP error
- [Update] Translation files
1.4.3
- [Fix] Error in PHP versions prior to 7.3 caused by a function call trailing comma
- [Fix] MySQL error in the dashboard widget if Metrics has ignored queries
- [Fix] "Remove All Ignored Queries" menu command doesn't work with SearchWP v4
- [Fix] Blocking search query logging by user ID doesn't work
- [Fix] Deprecation notices on PHP 8.2
1.4.2
- [New] Option to delete all the data Metrics has logged before a specific date
- [Change] Enhanced menu integration with modern versions on SearchWP
- [Fix] Required parameter error when instantiating \SearchWP_Metrics\Search class with a limited set of arguments
1.4.1
- [Fix] Handling of ignored queries with special characters
1.4.0
- [New] Ability to manually ignore (with
*wildcard support) - [Improvement] Bundler
- [Update] Dependencies
- [Update] Updated updater
1.3.2
- [Fix] SearchWP 4 compatibility fix when displaying some reports
1.3.1
- [NOTICE] The metadata table schema has been updated to be more capable. This update involves dropping and recreating the table. If you would like to retain this data: BACK UP the existing table before updating. Note that the data has not been used in Metrics to date, but you may have opted in to using it on your own since the introduction of the metadata table. This will be the final update to the metadata table schema. Metrics will be including additional reports based on metadata in future releases. If you are updating from version 1.2.4 or lower, there is nothing for you to do.
- [Change] Metadata table schema update
- [New] New filter
searchwp_metrics_meta_origin_use_idto log the referer ID instead of referer URL - [New] New action
searchwp_metrics_search_metafired when a search is performed
1.2.8
- [Fix] Error when SearchWP 4 is not active
- [Fix] Warning when SearchWP is not active
1.2.7
- [Fix] Permalink output when click tracking is enabled
- [Fix] Dashboard Widget display when using SearchWP 4
1.2.5
- [Fix] Omission of redundant core Stats links when using SearchWP 4
- [Fix] Handling of ignored queries when using SearchWP 4
- [Fix] Removes case sensitivity for Roles in blocklist
- [New] Adds meta table for storing metadata
- [New] Action
searchwp_metrics_searchwhen a search is run
1.2.4
- [Fix] Redundant URL encoding
- [Fix] Redundant Search Stats Dashboard link from core SearchWP Statistics feature
- [Fix] Click buoy SearchWP 4 compatibility
- [Update] Updated updater
1.2.3
- [Fix] SearchWP 4 integration issue
1.2.0
- [New] Adds SearchWP 4 compatibility
1.1
- [New] No Results details can now be exported
- [Improvement] When viewing Popular Search Details, click data is now included in export
- [Fix] Incorrect date range when viewing Popular Search Details
- [Fix] Expected behavior when overriding core SearchWP Statistics
- [Update] Link to documentation for Synonyms
- [Update] Dependencies
- [Update] Updated updater
1.0.9
- [New] Added additional parameters
hits_min,hits_maxwhen retrieving popular search queries over time - [Fix] Relocates hooks to make them more accessible to plugins
- [Fix] False positive when preventing duplicate click tracking
1.0.8
- [Improvement] Improved performance both when searching and viewing data
1.0.7
- [New] New filter
searchwp_metrics_dashboard_widgetto control whether the Dashboard Widget is displayed
1.0.6
- [New] New filter
searchwp_metrics_redirect_statusto modify the Status of click tracking redirects - [New] Chosen engines are now persisted and the defaults for the next viewing of Metrics
- [Fix] Automatically recreate database tables should they be lost (e.g. after moving a site)
- [Fix] Fixed an issue where some options were not removed during uninstallation (if that option is enabled)
- [Fix] Fixed an issue preventing click tracking with customized query parameters
1.0.4
- [Fix] Fixes an issue that prevented the uninstallation routine from running when enabled
1.0.3
- [Improvement] Improves performance when generating Insights
- [New] Settings button now has its own capability
- [New] New filter
searchwp_metrics_capability_settingsto modify the Settings button capability
1.0.2
- [Fix] Fixes PHP Notice for division by zero in certain circumstances
1.0.1
- [Fix] Fixes PHP Notice in Dashboard Widget when no data has been recorded
- [Fix] Fixes Fatal Error when SearchWP is not activated but Metrics is activated
- [Fix] Fixes Fatal Error due to case sensitivity of Events directory
1.0
- Initial release
