Glossary

SearchAction

A Schema.org structured data type used to explicitly define a website's search functionality, enabling the Sitelinks Search Box rich result in Google Search by specifying the search target URL and query parameter.

Get in touch Learn more

Stylish WeWork-like workspace with hot desks and document wall, professional searching through enterprise knowledge base on a mounted ultrawide display, warm industrial pendants overhead.

SCHEMA.ORG DEFINITION

What is SearchAction?

A structured data type that defines a website's internal search functionality for search engines, enabling the Sitelinks Search Box rich result.

SearchAction is a Schema.org type that programmatically describes a website's search engine endpoint by specifying the target URL template and the query-input parameter name. When implemented correctly, it enables the Sitelinks Search Box rich result, allowing users to perform site-scoped searches directly from the search engine results page.

The type is typically nested within a WebSite schema and requires a potentialAction property. The target field must contain a URL with a {search_term_string} placeholder, while query-input defines the corresponding parameter key. This explicit declaration helps search engines understand the site's search architecture without relying on heuristic crawling.

STRUCTURED DATA

Key Properties of SearchAction Markup

The SearchAction type defines a website's internal search engine endpoint, enabling the Sitelinks Search Box rich result. Proper implementation requires precise configuration of the target URL template and query parameter.

Target URL Template

The target property defines the URL pattern that receives the search query. It must include a placeholder for the user's search term.

Format: https://www.example.com/search?q={search_term_string}
The placeholder {search_term_string} is replaced by the user's actual query
The URL must point to a valid, functioning internal search results page
Encoding: The user's input is automatically URL-encoded when substituted
Common mistake: Using a static URL without the placeholder variable

Query Input Parameter

The query-input property specifies the name of the query parameter and how it accepts input from the user.

Required name: Must be set to search_term_string
Value specification: Use required name=search_term_string to indicate a mandatory input
This tells Google exactly which URL parameter receives the search query
The syntax follows the Schema.org Action input/output specification pattern
Incorrect naming is the most frequent cause of SearchAction markup rejection

JSON-LD Implementation

SearchAction is embedded within a WebSite schema type using JSON-LD, the recommended format by Google.

Nest SearchAction inside a potentialAction array on the WebSite entity
Place the script in the <head> or early in the <body> of the homepage
Example structure:
- @type: WebSite
- url: The canonical homepage URL
- potentialAction: Array containing the SearchAction object
Validate using Google's Rich Results Test tool before deployment

Sitelinks Search Box Trigger

Correct SearchAction markup enables the Sitelinks Search Box rich result, which appears directly below your site's main search result listing.

Provides a direct search bar for your site on the Google results page
Increases brand real estate and reduces friction for returning users
Eligibility: Only for sites that appear as a navigational result for brand queries
Google may not show the box even with valid markup; it's an algorithmic decision
The feature is distinct from the Google Programmable Search Engine

Common Validation Errors

Several implementation errors cause SearchAction markup to fail validation or be ignored by Google.

Missing placeholder: The target URL lacks {search_term_string}
Mismatched parameter name: The query-input name doesn't match the URL parameter
Non-canonical URL: The url property on WebSite doesn't match the site's canonical domain
Multiple SearchActions: Only one SearchAction should be defined per WebSite
Invalid encoding: The target URL contains unescaped characters that break the template

Relationship to WebSite Entity

SearchAction cannot exist independently; it must be a child of the WebSite schema type, which represents the entire site.

The WebSite type establishes the canonical entity for your domain
potentialAction is the property that links WebSite to SearchAction
Other potential actions like ReadAction or SubscribeAction can coexist in the array
The WebSite entity should also include name, url, and optionally publisher
This parent-child relationship helps search engines associate the search capability with the correct domain

Enabling Efficiency, Speed & Accuracy

Intelligent Analysis, Decision & Execution

We build AI systems for teams that need search across company data, workflow automation across tools, or AI features inside products and internal software.

Talk to Us

Search across company data

Give teams answers from docs, tickets, runbooks, and product data with sources and permissions.

Useful when people spend too long searching or get different answers from different systems.

Enterprise searchRAGPermissions

Automate internal workflows

Use AI to route work, draft outputs, trigger actions, and keep approvals and logs in place.

Useful when repetitive work moves across multiple tools and teams.

AI agentsWorkflow automationGovernance

Add AI to products and internal tools

Build assistants, guided actions, or decision support into the software your team or customers already use.

Useful when AI needs to be part of the product, not a separate tool.

AI integrationDecision supportModel routing

SEARCHACTION EXPLAINED

Frequently Asked Questions

Clear, technical answers to the most common questions about implementing the SearchAction schema type for Sitelinks Search Box rich results.

SearchAction is a Schema.org type used within WebSite structured data to explicitly define a website's internal search functionality. It specifies the URL target and query parameter that a search engine should use to programmatically execute a site search. When implemented correctly, this markup enables the Sitelinks Search Box rich result in Google Search, which places a search bar directly beneath your site's main listing, allowing users to search your site from the SERP itself. The SearchAction type is a subclass of Action, and it requires two critical properties: a target entry point containing a URL template with a {search_term_string} placeholder, and a query-input that defines the expected parameter name.

DEBUNKING MYTHS

Common Misconceptions About SearchAction

Clarifying the technical realities of the SearchAction schema type to ensure correct implementation and avoid common pitfalls that prevent the Sitelinks Search Box from appearing.

Myth: It Creates a Site Search Engine

SearchAction does not build or power a search engine. It is a structured data signal that tells search engines where your existing internal search engine is located and how to format a query for it. You must have a functioning site search at the specified target URL. The markup simply enables a shortcut box in the SERP; it does not index your content or provide search algorithms.

Myth: It's a Global, Site-Wide Setting

SearchAction is a page-level property of Organization or WebSite. While you typically place it on your homepage, it is technically scoped to the entity it describes. A common misconception is that it's a meta tag or a setting in Google Search Console. It must be embedded within a WebSite or Organization node in your JSON-LD block. Placing it on a single, non-homepage URL will not enable the feature site-wide.

Myth: Any URL Can Be the Target

The target URL must point to a valid, functional internal search results page on the same domain. Cross-domain targets are ignored. The URL template must use the {search_term_string} placeholder macro. For example:

Correct: https://example.com/search?q={search_term_string}
Incorrect: https://google.com/search?q=site:example.com+{search_term_string} Google validates that the target page returns a 200 status code and contains search functionality.

Myth: It Guarantees a Sitelinks Search Box

Implementation is a prerequisite, not a guarantee. Google uses SearchAction as a signal, but the final decision to display the Sitelinks Search Box is algorithmic. Factors include:

The site's overall authority and query volume.
Whether Google's systems determine a search box would be useful for users navigating to the site.
Correct technical implementation without syntax errors. Even with flawless markup, the feature may not appear for low-authority or new domains.

Myth: It Supports POST Requests

SearchAction only supports HTTP GET requests. The query-input property expects the search term to be passed as a URL query parameter. If your internal search engine uses a POST method with the query in the request body, you cannot use SearchAction to enable the Sitelinks Search Box. You would need to create a GET-compatible endpoint that redirects or proxies to your POST-based search.

Myth: It's a One-Time Setup

SearchAction requires ongoing monitoring and maintenance. Common failure points include:

URL Template Changes: If your search URL structure changes, the markup must be updated immediately.
Blocked Crawling: If robots.txt or X-Robots-Tag blocks Googlebot from the search results page, the feature will be disabled.
Page Removal: If the page containing the WebSite markup is deleted or noindexed. Regularly validate with the Rich Results Test tool.

About the author

Prasad Kumkar

CEO & MD, Inference Systems

Prasad Kumkar is the CEO & MD of Inference Systems and writes about AI systems architecture, LLM infrastructure, model serving, evaluation, and production deployment. Over 5+ years, he has worked across computer vision models, L5 autonomous vehicle systems, and LLM research, with a focus on taking complex AI ideas into real-world engineering systems.

His work and writing cover AI systems, large language models, AI agents, multimodal systems, autonomous systems, inference optimization, RAG, evaluation, and production AI engineering.

Limited slotsGet a Free AI Consultation

How We Work

Custom AI workflows for your Business

One-fit-all AI don't work for modern businesses. At Inferensys, we aim to understand your business & custom requirements; which we use to define most efficient agentic workflows, the data, and the tools for your business.