Tracking Site Search Keywords FAQ - Reports

Matomo supports multiple methods for tracking internal site search activity. These allow you to capture the search terms users enter into your site’s search feature, and optionally, the search category and the number of results returned.

By default, a search is tracked as a Site Search action using URL parameters and logged separately from pageviews. Site Search actions do not count as pageviews, which helps maintain accurate tracking of both navigation and search behaviour.

However, not all websites use this default query parameter format. Depending on how your website search is implemented, you can track internal site searches using one of the following methods:

URL parameters (default): When enabled, Matomo detects search keywords from the query string (e.g. ?q=analytics).
JavaScript method trackSiteSearch(): For sites that use rewritten URLs or need to track result counts and categories explicitly.
Tracking API: Relevant to advanced setups such as mobile apps or server-side logging.
Virtual pageviews: Logs searches as standard pageviews, which is useful when full Site Search reports are not needed.

Each method is suited to a different type of search implementation. The sections below explain how each one works and when to use it.

Track Site Search using URL Parameters (default)

The simplest way to track internal search keywords in Matomo is by detecting them from the query parameters in your website’s search result URLs.

By default, Matomo looks for any of the following query parameter names: q, query, s, search, searchword, k, keyword. If your search result URL includes one of parameters, e.g., https://example.com/search?q=analytics, Matomo will automatically log analytics as a Site Search action.

You can add custom query parameters for each website or apply the default parameters used globally (for all measurables). Read more on how to enable Site Search tracking using URL parameters.

Track Site Search using the JavaScript trackSiteSearch() function

Use the trackSiteSearch() method to use rewritten URLs like /search/keyword, or you want to manually track the number of returned search results, or you prefer to explicitly set the search keyword and category in your tracking code.

Instead of relying on automatic detection from the URL, you can manually track a Site Search action using the following JavaScript function: matomoTracker.trackSiteSearch(keyword, category, searchCount);

keyword: The term the user searched for (required).
category: The search category, if applicable (optional).
searchCount: The number of results returned (optional).

This method should be called on your search results page, and replaces the standard trackPageView() call for that page. Explore the Matomo JavaScript documentation for trackSiteSearch().

Track Site Search using the Tracking API (advanced)

For advanced use cases, can also record Site Search requests using the Matomo Tracking API and including the following parameters in your tracking request:

search: The search keyword (required).
search_cat: The category of the search (optional).
search_count: The number of results returned (optional).

Refer to the Tracking API Reference for full documentation on these parameters and how to structure the request.

Track No Result Search Keywords

The No Result Keywords report in Matomo shows all search terms that returned no results on your site. This helps identify content gaps and improve search experience.

If you are using the “Track Site Search using URL Parameters (default)” setup, the only way to track the number of search results on the page is to edit the JavaScript code, in the search result pages, to tell Matomo how many results are displayed. Once you have this number available in a JavaScript variable, you can add:

[...]
var searchCount = 15; // set this value when rendering the search result page
_paq.push(['setCustomUrl', document.URL + '&search_count=' + searchCount]);
_paq.push(['trackPageView']);
[...]

Matomo will then track for the site search query, the number of results, and will report all keywords with “zero” results in the “No Result Keywords” report.

Track Site Search using Virtual Pageviews

Another method for tracking site searches is to simulate a virtual pageview with a custom URL structure that includes the search keyword. It is a useful method when your Site Search does not use query parameters or when you prefer to track searches as standard pageviews rather than Site Search actions.

For example, if a visitor searches for analytics, you can manually trigger a virtual pageview for a rewritten URL such as: /search/analytics.

This approach does not populate the Site Search reports in Matomo. Instead, it records each search as a regular Page URL entry, which you can then analyse in the Pages reports.

You can implement virtual pageview tracking for site searches using the Matomo JavaScript tracking code or Matomo Tag Manager (MTM). Both implementation methods involve manually triggering a virtual pageview after the user submits a search, ensuring that the keyword is tracked correctly and not on every page load.

Add Custom JavaScript

To track internal site searches as virtual pageviews, you can add custom JavaScript to log the virtual pageviews after the user enters a keyword and submits the form.

This custom script should capture the keyword from the search input field and convert it to lowercase (to avoid duplicates). It should push a virtual pageview (e.g. /search/analytics) with a rewritten URL and redirect to the search results page (if required).

Example of a basic search form:

<form id="search-form">
  <label for="search">Search our site:</label>
  <input type="text" id="search" name="q" placeholder="Enter keyword">
  <button type="button" id="search-submit">Search</button>
</form>

Example of custom JavaScript code:

<script>
  document.getElementById('search-submit').addEventListener('click', function() {
    var keyword = document.getElementById('search').value.trim().toLowerCase();
    if (!keyword) return;

    _paq.push(['setCustomUrl', '/search/' + encodeURIComponent(keyword)]);
    _paq.push(['trackPageView']);

    // Delay to allow tracking before redirect
    setTimeout(function() {
      window.location.href = '/search.html?q=' + encodeURIComponent(keyword);
    }, 300);
  });
</script>

Note: You can use this code whether you’re implementing it directly in your website (using the Matomo tracking code) or within a Custom HTML Tag in Matomo Tag Manager.

This example assumes the button has the ID search-submit and the input field has the ID search. Adjust the selectors for your website where required.

Use the Matomo JS tracking code

Your standard Matomo tracking code should be placed in the <head> section of your website. This ensures that Matomo is fully initialised and ready to receive any manually triggered tracking commands. The tracking code enables automatic tracking of standard pageviews and other interactions. It must be loaded before any custom script attempts to push tracking data.

To track virtual pageviews for site searches, add your custom JavaScript before the closing </body> tag.
To avoid duplicate entries caused by different capitalisations (e.g. Analytics vs analytics), include a method in your script to force all search keywords to lowercase. This is handled in the example code by using: keyword = input.value.trim().toLowerCase();
For a complete working example, see the Add Custom JavaScript section above.

Use Matomo Tag Manager

If you are using Matomo Tag Manager to manage tracking on your website, you can implement virtual pageview tracking for site searches using a Custom HTML Tag. You do not need to define a separate variable in Tag Manager as the script handles everything internally.

In Tag Manager, go to Tags and click Create New Tag.
Choose the Custom HTML Tag Type and provide a descriptive name.
In the Custom HTML field, add your custom JavaScript that captures the search keyword, converts it to lowercase, and pushes a virtual pageview to Matomo. For a complete working example, see the Add Custom JavaScript section above.
Set the Position to Body End (where Tag Manager injects the script into your website’s HTML code).
Select a DOM Ready Trigger.
Use the Preview and Debug mode in Tag Manager to test your configuration.
Once tested, publish the changes to your live environment.

Implementing virtual pageview tracking using either the Matomo tracking code or Matomo Tag Manager useful when your website does not use query parameters for search or when you prefer to analyse searches in the Pages report rather than use Site Search reports.