Custom Search Parameter Tracking in WordPress
Custom search parameter tracking lets Search Insights record WordPress searches that do not use the default ?s= query parameter. Use it when your theme, search plugin, ecommerce search, documentation search, or headless WordPress frontend sends searches through a different URL parameter such as ?query=, ?keyword=, or ?search=.
WordPress core search usually uses ?s=search-term. Modern sites often change that pattern. Without custom parameter tracking, useful searches can be missed, which weakens the Search Insights dashboard, zero-result reporting, and content planning.
When you need a custom search parameter
| Search setup | Example URL pattern | Custom parameter needed? |
|---|---|---|
| Default WordPress search | /?s=analytics |
No, the default parameter is already supported. |
| Custom theme search | /?query=analytics |
Yes, configure query. |
| Documentation search | /docs/?keyword=exports |
Yes, configure keyword. |
| Headless frontend | /search?term=gdpr |
Yes, configure the parameter used by the frontend. |
| Ajax-only search | No visible URL parameter | Review the Ajax search integration guide. |
Find the parameter your site uses
Run a normal search on your website and look at the resulting URL. The parameter is the name after the question mark and before the equals sign. In https://example.com/?keyword=pricing, the parameter is keyword.
If your site uses multiple search forms, test each one. A header search, blog search, product search, and docs search may not all use the same parameter. Track the parameter that represents the search behavior you want to analyze.
Configure Search Insights
- Open your WordPress admin area.
- Go to the Search Insights settings.
- Find the custom search parameter field.
- Enter only the parameter name, not the full URL. Use
keyword, not?keyword=pricing. - Save the settings.
- Run a test search and confirm it appears in the dashboard.
After the test, check the query, origin page, and result status. If the search does not appear, verify the parameter name and confirm that the search is sent as a normal request rather than only through JavaScript.
Quality checks after setup
- Confirm the term is captured. Search for a unique phrase so it is easy to find in the dashboard.
- Check origin tracking. The origin page helps explain why visitors searched.
- Check zero-result behavior. A custom parameter should still reveal searches that fail.
- Review privacy. Do not send personal information through search parameters.
Common implementation issues
If the site has a search form that uses JavaScript, a custom parameter may not be enough. Some instant-search interfaces never load a results URL. In that case, the integration should send search events in a way Search Insights can record. Start with the Ajax guide, then test with a unique search term.
If your site has multiple parameters, avoid guessing. Pick the one that actually carries the search query. Parameters used for filters, categories, sorting, pagination, or tracking campaigns should not be treated as search terms.
How custom parameters improve SEO analysis
When custom search data is captured correctly, you can analyze the same signals as default WordPress search: popular searches, searches from specific pages, repeated support queries, and zero-result searches. That gives content teams a more complete view of visitor demand.
For ecommerce, custom parameters can reveal product synonyms and category language. For documentation sites, they can reveal missing guides. For membership sites, they can show onboarding confusion. The value depends on complete capture.
Parameter audit checklist
Run a short audit whenever search behavior changes. Test the homepage search, header search, mobile search, product search, documentation search, and any search form inside a modal or sidebar. Record the parameter name, the page where the test happened, and whether the query appeared in Search Insights.
If two search interfaces use different parameters, document both. If only one can be tracked immediately, prioritize the interface closest to conversion or support: product search, docs search, pricing-page search, and account-area search usually matter more than a low-use archive search.
Security and privacy considerations
Custom parameters should carry search intent, not private data. Do not configure parameters that contain names, email addresses, account IDs, tokens, or tracking payloads. If a custom frontend sends sensitive values through the URL, fix the search implementation before treating that parameter as analytics input.
Maintenance checklist
- Retest tracking after changing themes, search plugins, or frontend routing.
- Retest after adding a new product search, docs search, or resource library.
- Document the configured parameter so future developers know why it exists.
- Review exported data with the CSV and Excel export workflow after a few weeks.
Frequently asked questions
What is a custom search parameter in WordPress?
A custom search parameter is a URL query parameter other than WordPress core’s default s parameter that carries the visitor’s search term, such as query, keyword, or term.
Do I enter the full search URL in Search Insights?
No. Enter only the parameter name. For a URL such as /?keyword=pricing, the parameter name is keyword.
Will this track Ajax searches?
Only if the Ajax search exposes a query parameter or sends a request Search Insights can record. Pure JavaScript instant-search implementations may need Ajax-specific integration.