---
title: "Site search that works by URL · Specoria"
description: "Site search that works by URL: Agents query the catalog by search URL instead of clicking; script-only search forces them into a slow browser."
source_url: "https://specoria.com/method/checks/site-search/"
lang: "en"
---

[← All checks](https://specoria.com/method/checks/)
site_search

# Site search that works by URL

Why it matters Agents query the catalog by search URL instead of clicking; script-only search forces them into a slow browser.

**Category**
Action (cart and orders)

**Weight**
1 of 100 points

**Critical blocker**
No. If it fails, it only costs its own weight.

**Applies to**
Online stores

**Effort**
1-2 hours · developer

**Score model**
v2.4

## How we measure it

We look for search that works through a URL parameter on the homepage: a SearchAction in structured data or a search form sent with GET (q, s, search…). A script-only search box is a partial pass; no search fails.

### What the result page says

These are the sentences in the test result; “…” is replaced by what we found on your site.

- Passed Site search works with a URL parameter (e.g. /search?q=…).
- Partial There’s a search box, but it only works with script and can’t be queried by URL.
- Failed No site search was found.

## How to fix it

**Target:** Search submits a GET form to a URL parameter; WebSite data declares a SearchAction.

### Example code

`{
"@context": "https://schema.org",
"@type": "WebSite",
"url": "https://example.com",
"potentialAction": {
"@type": "SearchAction",
"target": "https://example.com/search?q=…",
"query-input": "required name=search_term_string"
}
}`
Example values (example.com, product name, price) are placeholders; replace them with your own.

### How to verify it yourself

A URL like https://example.com/search?q=test should open a results page directly.

### Fix it with an AI coding agent

Paste this into Claude Code, Cursor or another coding agent working on your store’s code. Review the change before you deploy it.

`You are working on my online store. Specoria’s agent readiness test checks the item below. Fix it so AI shopping agents can read the store and act on it.

## 1. Site search that works by URL (site_search)
Target: Search submits a GET form to a URL parameter; WebSite data declares a SearchAction.
Example fix (adapt it to this codebase and platform; example values are placeholders):
```
{
"@context": "https://schema.org",
"@type": "WebSite",
"url": "https://example.com",
"potentialAction": {
"@type": "SearchAction",
"target": "https://example.com/search?q=…",
"query-input": "required name=search_term_string"
}
}
```
Reference: https://specoria.com/method/checks/site-search/

## Rules
- First look through the codebase and tell me which files or templates you will change, before editing anything.
- Change only what these checks need, and keep the visible page and the structured data saying the same thing.
- Never invent prices, stock, shipping or return terms, reviews or product identifiers (GTIN): take them from the store’s real data or ask me.
- Don’t block or slow down real visitors and don’t add tracking.
- After deploying, run the free test again at https://specoria.com/ to verify the fix.`

## Specifications and guidance

- [schema.org/SearchAction ↗](https://schema.org/SearchAction)

The check is based on these open sources; links go to the publisher’s own pages.

## Where it sits in the 196-criteria framework

The result of this check counts as evidence for these items of the readiness framework:

- `0.site_search` Shopping flow (Specoria) section

[The framework and its source →](https://specoria.com/method/#criteria)

[← PreviousOrder tracking](https://specoria.com/method/checks/order-tracking/)[Next →Hotel structured data (Hotel / LodgingBusiness)](https://specoria.com/method/checks/lodging-schema/)

[Run the free test](https://specoria.com/method/checks/site-search/#test) [See the sample report →](https://specoria.com/reports/sample-report/)

## Related

- [Add-to-cart button in the initial HTML](https://specoria.com/method/checks/add-to-cart/)
- [Is the cart button accessible?](https://specoria.com/method/checks/cart-accessible/)
- [Agent simulator](https://specoria.com/agent-simulator/) Watch AI agents shop a store in a real browser
- [Agent protocol map: UCP, ACP, AP2, MCP, WebMCP](https://specoria.com/agent-protocols/) What each protocol does and what the free test checks

FREE TEST

## Test your store now

Enter your store’s address: 27 checks on your public pages, the way a shopping agent reads them.

The free test runs in your browser and needs JavaScript. [Request the free deep audit by email instead →](https://specoria.com/#contact)

Your result opens on its own page. Want the full picture? The free deep audit and panel come next, by email.