Skip to main content

Site search

Matomo's site-search report tells you what people expected to find. The searches that returned nothing are the most actionable rows in it, so the API makes a zero count explicit rather than something you have to remember to omit.

From your search handler​

use MatomoAnalytics\Facades\Matomo;

Matomo::siteSearch('invoices', category: 'docs', count: 7);

keyword is required; category scopes the search (a section, a filter, a tab) and count is the number of results.

Reading the keyword straight off the request saves repeating yourself:

Matomo::searchFromRequest(keywordKey: 'q', categoryKey: 'category', count: $results->total());

Both the keyword and the category come from the query string; if the keyword parameter is missing or blank, nothing is tracked — so this is safe to call on a controller that also renders an empty search page. A keyword of 0 is left out too, because Matomo cannot record a search for it.

Track the no-result searches​

Matomo::siteSearch($keyword, count: 0);

Passing 0 is not the same as passing nothing. A count of 0 records a search that found nothing, which is what populates Matomo's no-result report. Omitting the count records a search whose result count is unknown.

Automatically, per route​

Route::get('/search', SearchController::class)->middleware('matomo.search:q,category');

The middleware arguments are the query-parameter names — the first is the keyword key, the second (optional) the category key. It records a search on any GET response below status 400 — so a 3xx redirect counts, not only a 2xx — and only when the keyword parameter is actually present, so it does not fire on the bare search page.

The middleware cannot know the result count, because it runs after the response is built and does not inspect it. If you want counts — and you do want them, for the no-result report — call Matomo::siteSearch() or Matomo::searchFromRequest() from your handler instead, where the count is available.

A request that records a search sends no page view beside it, whether the search comes from matomo.search or from a call in your handler. Matomo counts a search as the action of its page, and with site search on for the website it also reads the keyword out of a page view's URL, so a page view next to the search would count the search twice. The page view middleware leaves such a request to the search, also when middleware.auto puts it on every route.

A page that loads @matomoScript sends its own page view from the browser, which Matomo records as the search when site search is on for the website. Track the search there on one side only.

What reaches Matomo​

The keyword becomes Matomo's search term, the category its search category, and the count its result count. A hit with a search term is a search action rather than a page view, so it appears in the site-search reports instead of inflating your page list.

Like every hit, it passes through the tracking gate. Note that URL redaction applies to the tracked URL, not to the search term — a search keyword is the data you asked to collect. If your search box can receive sensitive input, do not track it.