How to Add a Sitelinks Search Box with WebSite + SearchAction Schema
Understand with AI
Discuss with your preferred AI assistant
A single WebSite node with one SearchAction is all the markup the sitelinks search box requires.
The {search_term_string} placeholder is mandatory — it is where Google substitutes the user’s query.
Google reads the sitelinks search box markup from your site’s home page, ideally in the <head>.
A sitelinks search box is the search field Google can display directly inside your search result, letting people search your site without first clicking through to it. It is one of the highest-trust signals a brand can earn in the SERP — and it is powered by a tiny piece of structured data you control.
This guide explains what the sitelinks search box is, how the underlying WebSite and SearchAction markup works, and exactly how to implement it correctly so you give Google everything it needs to consider showing the box for your brand.
What Is a Sitelinks Search Box?
When someone searches for your brand name, Google sometimes shows an enhanced result with an embedded search field. A query typed there is sent straight to your own on-site search results page, bypassing a second Google search entirely. That keeps users inside your funnel and signals to searchers that your site is an authoritative, searchable destination.
Google decides whether to show the box algorithmically — you cannot force it. But you can make it eligible, and you can tell Google which search URL to use, by adding WebSite structured data with a SearchAction. Without that markup, Google may guess your search URL or skip the box altogether.
How the WebSite + SearchAction Markup Works
The markup is a single JSON-LD block describing your homepage as a WebSite node with one potentialAction of type SearchAction. Three parts do the work:
- url — the canonical homepage of your site, e.g. https://example.com.
- target — your search results URL with a placeholder showing where the query goes, written as https://example.com/search?q={search_term_string}.
- query-input — the line required name=search_term_string that ties the placeholder to the user's typed query.
The token {search_term_string} is a variable, not literal text. When a user searches "running shoes", Google substitutes that term into the target URL, producing https://example.com/search?q=running%20shoes. The name inside the braces must match the name in the query-input line exactly.
How to Add a Sitelinks Search Box, Step by Step
1. Find your real search URL
Run a search on your own site and copy the resulting URL. Note the query parameter — most sites use ?q=, ?s=, or ?search=. Replace your typed term with {search_term_string} so the template reads, for example, https://example.com/?s={search_term_string}.
2. Generate the JSON-LD
Use the generator above: enter your site name, homepage URL, and the search URL template. It produces a valid WebSite + SearchAction block and flags common mistakes such as a missing token, a non-HTTPS URL, or a search endpoint on a different domain.
3. Place it on your homepage
Paste the <script type="application/ld+json"> block into the <head> of your homepage. Google reads this markup from the home page, so it does not need to be on every page — though keeping a single sitewide WebSite node is also fine.
4. Validate and confirm
Run the page through Google's Rich Results Test and the Schema Markup Validator to confirm the structured data parses with no errors. Then request indexing in Search Console so Google re-crawls the updated homepage.
Best Practices and Requirements
- Mark up only your homepage as the WebSite node, and point url at the site root, not a deep page.
- Use HTTPS consistently across the site URL and the search URL.
- Keep the search endpoint on the same domain as your site so the box stays inside your funnel.
- Make sure your on-site search actually works for any query — Google may test it, and a broken results page hurts trust.
- Use only one SearchAction per WebSite node with a single search-term variable.
- Match the brand name in name to the brand Google already associates with your domain.
Common Mistakes to Avoid
- Forgetting the {search_term_string} token, so Google has no place to insert the query.
- Letting the token name and the query-input name drift out of sync.
- Percent-encoding the braces (%7B...%7D), which breaks variable substitution.
- Pointing the search URL at a third-party search engine instead of your own results page.
- Expecting the box to appear instantly — eligibility depends on Google ranking your site for its own brand query first.
Expert Tips
Copy your search URL from a real query
Run an actual search on your site and copy the resulting URL, then swap your term for {search_term_string}. This guarantees the template matches the parameter your site really uses (?q=, ?s=, ?search=).
Validate before you wait
Test the page in Google’s Rich Results Test and confirm the JSON-LD parses cleanly, then request indexing. Eligibility still depends on Google ranking your brand query, but clean markup removes every avoidable blocker.
Frequently Asked Questions
Why is my sitelinks search box not showing?
The box is shown at Google's discretion. The most common reasons it does not appear are that your site is not yet ranked strongly for its own brand name, the WebSite markup is missing or invalid, or Google simply has not recrawled the homepage since you added it. Valid markup makes you eligible but never guarantees the box.
What is search_term_string in the schema?
It is a placeholder variable, not literal text. You write it as {search_term_string} inside your search URL template and again in the query-input line as "required name=search_term_string". When a user searches, Google replaces the placeholder with their actual query to build the live results URL.
Where should I place the WebSite SearchAction markup?
On your homepage, ideally inside the <head> as a JSON-LD script. Google reads the sitelinks search box markup from the site's home page. A single sitewide WebSite node is also acceptable, but only one SearchAction should be defined.
Can I use a string target or do I need an EntryPoint object?
Both are valid. The compact string form (target set directly to the URL template) is what Google's documentation shows and is the simplest. The verbose EntryPoint object form is equivalent and useful when you are combining nodes in a larger graph. The generator above can emit either.