WebSite schema with SearchAction: your own search box in Google

What is the sitelinks search box?

If you have ever searched for a large brand or popular website in Google, you have probably already seen it: a search box that appears directly in the search results, below the sitelinks of the website. This search box allows users to search directly within that specific website, without first visiting the site. It is a powerful feature that improves the user experience and increases your site's visibility.

Behind this functionality lies the WebSite schema combined with a SearchAction. By adding this structured data to your homepage, you tell Google that your site has an internal search function and how it can be invoked. Google can then decide to show that search box in the search results when someone searches for your brand or domain.

The sitelinks search box is more than a visual enhancement. It is a signal to search engines and AI models that your website is a full-fledged information portal with searchable content. This fits within the broader strategy of Schema.org implementation to make your site optimally discoverable by machines.

Implementing WebSite schema with SearchAction

The implementation consists of a JSON-LD block that you place on the homepage of your website. The block contains the WebSite type with a potentialAction of type SearchAction. The SearchAction describes how your internal search function works: which URL is called and where the search term is inserted.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "name": "AEO Expert",
  "url": "https://aeo-expert.nl/",
  "potentialAction": {
    "@type": "SearchAction",
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "https://aeo-expert.nl/search?q={search_term_string}"
    },
    "query-input": "required name=search_term_string"
  }
}
</script>

Let us break down each part of this block. The "@type": "WebSite" tells machines that this schema describes the entire website, not an individual page. The "name" and "url" identify your site. The crucial part is the "potentialAction": this describes an action that can be performed on the site.

The urlTemplate explained

The urlTemplate contains the URL of your search page with a placeholder for the search term. The placeholder {search_term_string} is replaced by the actual search term the user enters. The name of the placeholder must match the name you specify in "query-input".

• The urlTemplate must refer to a working search page on your site that actually displays search results.
• The placeholder name (search_term_string) must match exactly in both the urlTemplate and the query-input.
• The search page must show results that are relevant to the entered search term. Empty or irrelevant results can lead to removal of the search box.
• Google only supports HTTP GET-based search functions. POST-based search forms do not work with SearchAction.

Advanced SearchAction configurations

The basic implementation suffices for most websites, but advanced configurations are possible that describe your search functionality more richly.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "name": "Webshop Example",
  "url": "https://webshop.nl/",
  "potentialAction": [
    {
      "@type": "SearchAction",
      "target": {
        "@type": "EntryPoint",
        "urlTemplate": "https://webshop.nl/search?q={search_term_string}"
      },
      "query-input": "required name=search_term_string"
    },
    {
      "@type": "SearchAction",
      "target": {
        "@type": "EntryPoint",
        "urlTemplate": "android-app://com.webshop.app/https/webshop.nl/search?q={search_term_string}"
      },
      "query-input": "required name=search_term_string"
    }
  ]
}
</script>

In this example two SearchActions are defined: one for the website and one for the Android app. Google can use both, depending on the user's device. The app link uses the Android deep linking protocol to open the search query directly in the app.

Combining WebSite schema with Organization

In practice you combine the WebSite schema with an Organization schema to provide a complete picture of your company and website. The Organization describes who you are, the WebSite describes what your site offers. By including sameAs links in the Organization schema, you also strengthen your digital identity.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://aeo-expert.nl/#organization",
      "name": "AEO Expert",
      "url": "https://aeo-expert.nl/",
      "logo": {
        "@type": "ImageObject",
        "url": "https://aeo-expert.nl/images/logo.png"
      },
      "sameAs": [
        "https://www.linkedin.com/company/kobalt-digital",
        "https://twitter.com/kobaltdigital"
      ]
    },
    {
      "@type": "WebSite",
      "@id": "https://aeo-expert.nl/#website",
      "name": "AEO Expert",
      "url": "https://aeo-expert.nl/",
      "publisher": { "@id": "https://aeo-expert.nl/#organization" },
      "potentialAction": {
        "@type": "SearchAction",
        "target": {
          "@type": "EntryPoint",
          "urlTemplate": "https://aeo-expert.nl/search?q={search_term_string}"
        },
        "query-input": "required name=search_term_string"
      }
    }
  ]
}
</script>

Requirements and limitations of the sitelinks search box

Not every website qualifies for the sitelinks search box. Google sets a number of requirements that you must meet.

1. Your website must have a working internal search function that shows relevant results for entered search terms.
2. The WebSite schema with SearchAction must be correctly implemented on the homepage of your site.
3. Your site must have sufficient authority and search volume. Small or new websites typically do not get a sitelinks search box.
4. The search results page must provide a good user experience: fast load times, relevant results and clear navigation.
5. Google must regularly crawl and index your site. Do not block the search results page via robots.txt or noindex.

If you do not want Google to show a search box (for example because your search function is limited), you can explicitly indicate this with a nositelinksearchbox meta tag.

<!-- Prevent the sitelinks search box -->\n<meta name="google" content="nositelinksearchbox" />

WebSite schema and AI models

The WebSite schema with SearchAction is not only relevant for Google's search results. AI models use this markup to understand that your site is a searchable information portal.

When an AI model reads the WebSite schema, it learns three things. First, that your site is a coherent whole with a clear identity (name, url). Second, that your site offers an internal search function, indicating a substantial amount of content. Third, how that search function technically works, which is potentially relevant for future AI agents that want to search your site.

With the rise of AI agents that autonomously search the web, the SearchAction becomes increasingly valuable. An AI agent that knows how your search function works can find information on your site in a targeted way without crawling every individual page. This is a preview of the AEO future where websites are not just passively read, but actively queried by machines.

The sitelinks search box is the visible tip of the iceberg. Beneath the surface, WebSite schema tells every machine that is listening: this site is a searchable knowledge portal.

Validating your implementation

After adding the WebSite schema with SearchAction, you must thoroughly test the implementation.

• Use the Google Rich Results Test to verify that your markup is correct and qualifies for the search box.
• Manually test the urlTemplate by replacing the placeholder with a search term and verifying that the correct search results page loads.
• Check Google Search Console for any validation errors reported for your WebSite schema.
• Search Google for your brand name and check whether the sitelinks search box appears. It can take several weeks after implementation.
• Test with different search terms to verify that your search function returns relevant results.

Key takeaways

• WebSite schema with SearchAction enables Google to show a search box in search results, allowing users to search your site directly from the SERP.
• The implementation requires a working internal search function and a correctly configured urlTemplate with a placeholder for the search term.
• Always combine WebSite schema with Organization schema via a @graph array for a complete structured picture of your company and site.
• AI models use WebSite schema to understand that your site is a searchable information portal, strengthening your authority.
• The sitelinks search box is not guaranteed. Google determines based on site authority, search volume and search function quality whether the box is shown.

Frequently asked questions

The sitelinks search box transforms your search result from a static link into an interactive portal. It is the first step towards a web where machines do not just read your site, but actively collaborate with it.