Skip to content
Browse all guides

Issue #234 · important

Issue 234

What is this issue?

The homepage WebSite schema is present but missing the SearchAction property, preventing Google from displaying a Sitelinks Search Box beneath the homepage result for branded queries.

Without SearchAction in WebSite schema:

  • Google won't display a Sitelinks Search Box under your homepage result
  • Users can't search your site directly from Google search results
  • Branded search results won't have the enhanced search functionality
  • You'll miss an opportunity to improve user experience from search

A proper SearchAction should be nested inside WebSite schema and include: potentialAction with @type (SearchAction), target with urlTemplate containing {search_term_string}, and query-input.

Why does it matter?

SearchAction in WebSite schema is important for user experience:

  • Sitelinks Search Box: Enables users to search your site directly from Google search results
  • Branded search enhancement: Improves the appearance of branded search results
  • User convenience: Users can search your site without navigating to it first
  • Click-through rates: Enhanced search results may improve CTR
  • AI search readiness: AI engines understand your site has search functionality

Important: Only implement this if your site actually has functional internal search. Don't add SearchAction if your site doesn't have search capability.

Resolving this issue improves your SEO health score by enhancing branded search results for users.

How to fix it

  1. Ensure WebSite schema exists: Make sure your homepage has WebSite schema (see issue-58.md)

  2. Add SearchAction to WebSite schema on your homepage:

    {
  "@context": "https://schema.org",
  "@type": "WebSite",
  "url": "https://www.example.com",
  "potentialAction": {
    "@type": "SearchAction",
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "https://www.example.com/search?q={search_term_string}"
    },
    "query-input": "required name=search_term_string"
  }
}

  3. Use the correct URL template:

    • WordPress: /?s={search_term_string}
    • Shopify: /search?q={search_term_string}
    • Custom: Use your site's actual search URL pattern

  4. Test the search URL: Make sure the search URL returns real results

  5. Only implement if your site has functional internal search - Don't add this if you don't have search functionality

  6. Validate with Google's Rich Results Test

Examples

Example 1: Missing SearchAction in WebSite Schema

Problematic state (WebSite without SearchAction):

{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "url": "https://www.example.com"
}

Missing potentialAction with SearchAction

Corrected state:

{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "url": "https://www.example.com",
  "potentialAction": {
    "@type": "SearchAction",
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "https://www.example.com/search?q={search_term_string}"
    },
    "query-input": "required name=search_term_string"
  }
}

Example 2: SearchAction for WordPress Site

Corrected state (WordPress):

{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "url": "https://www.example-wordpress.com",
  "potentialAction": {
    "@type": "SearchAction",
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "https://www.example-wordpress.com/?s={search_term_string}"
    },
    "query-input": "required name=search_term_string"
  }
}

Example 3: SearchAction for Shopify Store

Corrected state (Shopify):

{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "url": "https://store.myshopify.com",
  "potentialAction": {
    "@type": "SearchAction",
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "https://store.myshopify.com/search?q={search_term_string}"
    },
    "query-input": "required name=search_term_string"
  }
}

How PixyScan detects this

PixyScan follows these logical steps to detect missing SearchAction:

  1. Check homepage only: The crawler specifically examines the homepage (index page) of the website

  2. Find WebSite schema: The crawler looks for WebSite schema on the homepage

  3. Check for SearchAction: The crawler verifies if the WebSite schema has:

    • potentialAction property
    • potentialAction.@type set to SearchAction

  4. Validate SearchAction completeness: If SearchAction is found, the crawler checks for:

    • target property with urlTemplate containing {search_term_string}
    • query-input property

  5. Check if site has search: The crawler also verifies if the site actually has internal search functionality

  6. Trigger conditions: The issue is flagged when:

    • WebSite schema exists but potentialAction with SearchAction is missing
    • Site has internal search but SearchAction is not declared
    • SearchAction exists but urlTemplate doesn't contain {search_term_string}

References