Title: SmartMatch Search Author: Burst Statistics B.V. Published: August 24, 2026 Last modified: August 24, 2026 --- Search plugins ![](https://ps.w.org/smartmatch-search/assets/banner-772x250.png?rev=3664878) ![](https://ps.w.org/smartmatch-search/assets/icon-256x256.png?rev=3664878) # SmartMatch Search By [Burst Statistics B.V.](https://profiles.wordpress.org/burstbv/) [Download](https://downloads.wordpress.org/plugin/smartmatch-search.1.0.0.zip) * [Details](https://wordpress.org/plugins/smartmatch-search/#description) * [Reviews](https://wordpress.org/plugins/smartmatch-search/#reviews) * [Installation](https://wordpress.org/plugins/smartmatch-search/#installation) * [Development](https://wordpress.org/plugins/smartmatch-search/#developers) [Support](https://wordpress.org/support/plugin/smartmatch-search/) ## Description SmartMatch Search keeps the normal WordPress search results intact and surfaces the most semantically relevant post(s) on top as a “Best match” suggestion. #### Search that understands intent Classic WordPress search matches keywords: when the words in the query do not literally appear in a post, the visitor gets “nothing found” — even when your site has exactly the right page. SmartMatch Search judges meaning instead, so visitors can search the way they actually talk: * “page where I can find my orders” surfaces your **Order history** page, even though none of those words appear in its title. * “how do I get my money back” finds your **Returns & refunds** policy — no overlap in wording needed. * “wo finde ich meine rechnung” (German) still lands on your **Invoices** page: the model matches meaning across languages, so visitors searching in their own language get the right result. * “cancel my subscription” surfaces **Manage your membership**, instead of every post that happens to contain the word “cancel”. * “what time are you open on saturday” finds your **Contact & visiting information page. And it filters as well as it finds: a query like “burst viewer” will not match a post just because the word “burst” appears somewhere — only posts that are genuinely about the topic are suggested. The native results stay untouched below the suggestion, so search never gets worse, only better. #### Why SmartMatch Search connects to Burst The Burst Statistics integration exists for two reasons: 1. **Real visitors only.** Every AI search is a paid model call, so you only want to spend it on real people. Burst already knows which visits are validated human visits — its tracking filters out bots, crawlers and spam before a visit is recorded, in both cookie and cookieless mode. SmartMatch Search runs the AI only for those validated visits; bots silently get the normal search results at zero AI cost. 2. **Searches land in your statistics.** Searches run through the normal WordPress search request, so they show up directly in Burst’s Engagement tab. You see what visitors are looking for — and where your content falls short — in the same dashboard you already use. #### How it works SmartMatch Search is a thin integration layer between two plugins: * **AI** (`WordPress\AI`) — supplies the configured provider and text model. Provider/ model selection is delegated entirely to the AI plugin via WordPress\AI\get_ai_service() and the `wpai_preferred_text_models` filter. * **Burst Statistics / Burst Pro** — supplies visit validation. The AI search only runs for a _validated_ Burst visit (a uid with a recorded hit in the last 30 minutes), which excludes bots. Works in both cookie mode (`burst_uid` cookie) and cookieless mode (session fingerprint). How it works on a search request (`?s=...`): 1. The visitor must be a validated Burst visit, otherwise the native results are shown untouched. 2. Public, published posts of public post types are collected (title + excerpt, capped, freshest first) and sent to the model with the search term. 3. The model returns only the genuinely relevant post IDs, ranked. 4. Those posts are merged into the main query’s result array itself (via the the_posts filter): prepended above the native matches, de-duplicated, and optionally tagged with a configurable badge (via `the_title`). Because the change happens at the data layer, placement does not depend on how the theme renders the loop — it works the same for classic templates and block themes. When the native search found nothing, the suggestions become the results so the page is not empty. 5. Results are cached per search term (transient), invalidated when the candidate set changes. Suggestions appear on the first results page only. If the AI is unavailable, errors, or finds nothing relevant, nothing is added and the normal results (or “nothing found”) are displayed as usual. ### Settings The plugin adds a “SmartMatch Search” item to the Burst settings menu (Statistics Settings SmartMatch Search), with the options stored in the Burst settings store: * **Daily search budget** (default 50, seeded on activation) — the maximum number of AI searches per day. Only actual model calls count (cached rankings are free); once the budget is spent, visitors get the normal search results until the site’s next midnight. * **Posts sent to the AI** (default 200) — how many posts (most recently updated first) are sent to the model as candidates per search. More posts improve coverage on large sites, but raise the token cost per search. * **Excerpt length in words** (default 40) — how many words of each post are included in the prompt. Longer excerpts give the model more context to judge relevance, but increase token usage per search. * **Badge for the suggested result** (default empty) — text shown before the title of the suggested result, e.g. “(Best match)”, so visitors see why it is on top. Leave empty to show the suggestion without a badge. * **Prompt customization** — extra instructions appended to the system instruction sent to the model, e.g. to prioritize certain content or set a tie-breaking rule. Editing the prompt customization or excerpt length invalidates previously cached rankings, so changes take effect immediately. ### Filters * `smartmatch_search_enabled` (bool, WP_Query) — disable per query. * `smartmatch_search_is_validated_visit` (bool, uid) — override the visit gate. * `smartmatch_search_post_types` (string[]) — post types to search. * `smartmatch_search_candidate_limit` (int) — override the configured number of candidate posts sent to the model. * `smartmatch_search_excerpt_words` (int) — override the configured excerpt length in words. * `smartmatch_search_cache_ttl` (int seconds, default 1 hour) — ranking cache. * `smartmatch_search_suggestion_count` (int, default 1) — how many to surface. * `smartmatch_search_badge_label` (string) — override the configured badge text; an empty string disables the badge. * `smartmatch_search_badge_html` (string) — replace the rendered badge markup; an empty string suppresses the badge. The result is passed through wp_kses_post() before it is output. * `smartmatch_search_rate_limit` (int, default 5) — AI searches per IP / window. * `smartmatch_search_rate_window` (int seconds, default 5 min) — the window. * `smartmatch_search_daily_budget` (int) — override the configured daily budget. * `smartmatch_search_debug` (bool) — toggle debug logging (see Testing). * `wpai_preferred_text_models` (from the AI plugin) — choose provider/model. * `smartmatch_search_ranked` (action: ids, term, WP_Query) — observe results. * `smartmatch_search_rate_limited` (action: term, WP_Query) — fired when an IP exceeds the limit and falls back to normal search. * `smartmatch_search_budget_exceeded` (action: term) — fired when an AI search is skipped because the daily budget is spent. ### Testing / diagnostics Define `SMARTMATCH_SEARCH_BYPASS_GATES` as true (e.g. in wp-config.php) to disable the visitor gates — the Burst uid validation and the per-IP rate limit — so AI search runs without a tracked Burst visit. Useful for local testing or to verify a production setup where no validated visit is available. It does NOT bypass the dependency, main-query or relevance checks. Leave it undefined in normal use. ``` define( 'SMARTMATCH_SEARCH_BYPASS_GATES', true ); ``` Define `SMARTMATCH_SEARCH_DEBUG` as true to log every point where AI search bails out silently to the PHP error log (prefixed “[SmartMatch Search]”): missing dependencies, no validated visit, rate limit hit, no AI credentials, provider unsupported, SDK exception, unparseable response, nothing relevant, or the IDs finally selected. When the constant is undefined, logging follows WP_DEBUG; the smartmatch_search_debug filter can override it. Logging stays off in normal use. ``` define( 'SMARTMATCH_SEARCH_DEBUG', true );

Rate limiting

``` To curb abuse and AI cost, each IP may run at most 5 AI searches per rolling 5- minute window (both filterable). Beyond that, the request falls back to normal WordPress search. Only searches that trigger an actual model call count against the limit: cached rankings are served freely. The visitor IP is resolved through Burst’s own proxy-aware detector (`Burst\Frontend\Ip\Ip::get_ip_address()`) and is only stored hashed. ### Requirements Both the “AI” plugin and Burst Statistics (free) or Burst Pro must be active. The AI plugin needs a configured provider with valid credentials. The AI plugin is declared through the WordPress “Requires Plugins” header, so WordPress itself enforces it on activation. The Burst requirement is enforced at runtime instead( with an admin notice when missing): that header is an AND-list of wordpress.org slugs, so it cannot express “Burst free OR Burst Pro”, and Burst Pro is not distributed on wordpress.org. The plugin simply stays inactive (and tells you why) until both are present. ### External services SmartMatch Search does not connect to any service of its own and sends no data to Burst or SmartMatch servers. When a search qualifies for AI ranking, the search term and the candidate posts (post ID, post type, title and a short excerpt of public, published content) are sent to the AI provider that you yourself configured in the WordPress “AI” plugin — which provider that is depends entirely on your configuration there, and its terms of service and privacy policy apply to those requests. This happens only for validated human visits, within the configured daily budget, and only when the ranking is not already cached. No other data (no IP addresses, no visitor identifiers) is included in these requests. ## Installation 1. Install and activate the “AI” plugin (https://wordpress.org/plugins/ai/) and configure a provider with valid credentials in its settings. 2. Install and activate Burst Statistics (free) or Burst Pro. 3. Install and activate SmartMatch Search. 4. Optionally adjust the settings under Statistics Settings SmartMatch Search ( daily search budget, badge, prompt customization). That is all: your search form and results template keep working as before, and the AI suggestion appears on top of the results for validated human visits. ## FAQ ### Why does SmartMatch Search require Burst Statistics and the AI plugin? Every AI search is a paid model call, so you only want to spend it on real people. Burst already knows which visits are validated human visits — its tracking filters out bots, crawlers and spam in both cookie and cookieless mode — so SmartMatch Search runs the AI only for those visits; bots silently get the normal search results at zero cost. The AI plugin supplies the provider and model: you configure your AI credentials once, centrally, and this plugin simply uses that configuration. ### How do I keep the AI costs under control? Four mechanisms bound the spend. Only validated human visits trigger a model call; each IP is rate-limited (5 AI searches per 5 minutes by default); rankings are cached per search term, and cached results cost nothing; and the daily search budget (default 50) caps the total number of model calls per day. Once the budget is spent, visitors simply get the normal search results until the site’s next midnight. ## Reviews There are no reviews for this plugin. ## Contributors & Developers “SmartMatch Search” is open source software. The following people have contributed to this plugin. Contributors * [ Burst Statistics B.V. ](https://profiles.wordpress.org/burstbv/) * [ Hessel de Jong ](https://profiles.wordpress.org/hesseldejong/) * [ Rogier Lankhorst ](https://profiles.wordpress.org/rogierlankhorst/) * [ Shalin Shah ](https://profiles.wordpress.org/sh4lin/) * [ Parth Vaswani ](https://profiles.wordpress.org/parthnvaswani/) [Translate “SmartMatch Search” into your language.](https://translate.wordpress.org/projects/wp-plugins/smartmatch-search) ### Interested in development? [Browse the code](https://plugins.trac.wordpress.org/browser/smartmatch-search/), check out the [SVN repository](https://plugins.svn.wordpress.org/smartmatch-search/), or subscribe to the [development log](https://plugins.trac.wordpress.org/log/smartmatch-search/) by [RSS](https://plugins.trac.wordpress.org/log/smartmatch-search/?limit=100&mode=stop_on_copy&format=rss). ## Changelog #### 1.0.0 * July 9th, 2026 * New: Initial release. ## Meta * Version **1.0.0** * Last updated **3 days ago** * Active installations **Fewer than 10** * WordPress version ** 7.0 or higher ** * Tested up to **7.1** * PHP version ** 8.0 or higher ** * Tags * [ai search](https://wordpress.org/plugins/tags/ai-search/)[search](https://wordpress.org/plugins/tags/search/) [semantic search](https://wordpress.org/plugins/tags/semantic-search/)[site search](https://wordpress.org/plugins/tags/site-search/) [smart search](https://wordpress.org/plugins/tags/smart-search/) * [Advanced View](https://wordpress.org/plugins/smartmatch-search/advanced/) ## Ratings No reviews have been submitted yet. [Your review](https://wordpress.org/support/plugin/smartmatch-search/reviews/#new-post) [See all reviews](https://wordpress.org/support/plugin/smartmatch-search/reviews/) ## Contributors * [ Burst Statistics B.V. ](https://profiles.wordpress.org/burstbv/) * [ Hessel de Jong ](https://profiles.wordpress.org/hesseldejong/) * [ Rogier Lankhorst ](https://profiles.wordpress.org/rogierlankhorst/) * [ Shalin Shah ](https://profiles.wordpress.org/sh4lin/) * [ Parth Vaswani ](https://profiles.wordpress.org/parthnvaswani/) ## Support Got something to say? Need help? [View support forum](https://wordpress.org/support/plugin/smartmatch-search/)