Search analytics¶

See how visitors search: volume, top queries, queries with no results, and how filters and sorting options are used.

Tips & tricks

Address the top searches that return no results first by adding synonyms or content for them.

Show the top searches with no results for my website over the last 30 days.

Give getTopSearches or getSearchOverview a comparison period to populate changePercent, which surfaces the fastest-rising queries rather than just the highest-volume ones.

Show my website's top searches for the last 30 days versus the previous 30 days, sorted by biggest increase.

Ask the assistant to triage no-result searches: which to fix with a synonym, which to send to an existing page with a redirect, and which point to products worth adding to the catalogue.

Review my website's no-result searches and group them into: fix with a synonym, set up a redirect, or add a product to the catalogue.

getSearchOverview¶

Get the overall search performance overview for a customer website using Hello Retail: site-wide totals (searches, clicks, CTR, conversions, revenue) plus a per-feature breakdown (product, category, brand, suggested products, zero-result content, etc.). Numbers mirror the Search Analytics overview cards exactly. Optionally scope to specific search configs and compare against an earlier period for changePercent.

Name	Type	Required	Description
`websiteUuid`	string	Yes	The UUID of the customer's website in Hello Retail. Use `getWebsiteInfo` to look up available websites, or find it in my.helloretail.com under Settings → Website Settings → Website Unique Id.
`startDate`	string	No	Start of the window, inclusive, ISO YYYY-MM-DD. Defaults to 30 days before endDate.
`endDate`	string	No	End of the window, inclusive, ISO YYYY-MM-DD. Defaults to today.
`comparisonStartDate`	string	No	Comparison-period start, inclusive, ISO YYYY-MM-DD. Supply with `comparisonEndDate` to get `changePercent`.
`comparisonEndDate`	string	No	Comparison-period end, inclusive, ISO YYYY-MM-DD. Supply with `comparisonStartDate` to get `changePercent`.
`keys`	string[]	No	Search-config UUIDs to scope to (from `listSearchConfigs`). Omit for all of the website's configs.

Example request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "getSearchOverview",
    "arguments": {
      "websiteUuid": "<string>"
    }
  }
}

Returns

{
  "totals": {
    "searches": 0,
    "totalMaxResults": 0,
    "clicks": 0,
    "clickThroughRate": 0.0,
    "directConversions": 0,
    "directConversionRate": 0.0,
    "directRevenue": 0.0,
    "indirectRevenue": 0.0,
    "changePercent": null
  },
  "features": [
    {
      "feature": "<string>",
      "clicks": 0,
      "clickThroughRate": 0.0,
      "directConversions": 0,
      "directConversionRate": 0.0,
      "indirectConversions": 0,
      "directRevenue": 0.0,
      "indirectRevenue": 0.0,
      "changePercent": null
    }
  ]
}

getTopSearches¶

List the most-run search queries for a customer website using Hello Retail, ranked by search volume. Each row reports the query, its search count, max result count, clicks, click-through rate, and direct conversion / revenue metrics. Numbers mirror the Search Analytics "All Searches" table exactly. Optionally scope to specific search configs and compare against an earlier period.

Name	Type	Required	Description
`websiteUuid`	string	Yes	The UUID of the customer's website in Hello Retail. Use `getWebsiteInfo` to look up available websites, or find it in my.helloretail.com under Settings → Website Settings → Website Unique Id.
`startDate`	string	No	Start of the window, inclusive, ISO YYYY-MM-DD. Defaults to 30 days before endDate.
`endDate`	string	No	End of the window, inclusive, ISO YYYY-MM-DD. Defaults to today.
`comparisonStartDate`	string	No	Comparison-period start, inclusive, ISO YYYY-MM-DD. Supply with `comparisonEndDate` to get `changePercent`.
`comparisonEndDate`	string	No	Comparison-period end, inclusive, ISO YYYY-MM-DD. Supply with `comparisonStartDate` to get `changePercent`.
`keys`	string[]	No	Search-config UUIDs to scope to (from `listSearchConfigs`). Omit for all of the website's configs.
`limit`	integer	No	Maximum number of queries to return. Default 20, capped at 100.

Example request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "getTopSearches",
    "arguments": {
      "websiteUuid": "<string>"
    }
  }
}

Returns

{
  "results": [
    {
      "query": "<string>",
      "metrics": {
        "searches": 0,
        "totalMaxResults": 0,
        "clicks": 0,
        "clickThroughRate": 0.0,
        "directConversions": 0,
        "directConversionRate": 0.0,
        "directRevenue": 0.0,
        "indirectRevenue": 0.0,
        "changePercent": null
      }
    }
  ]
}

getTopSearchesWithoutResults¶

List search queries that returned no results for a customer website using Hello Retail, ranked by volume. These are missed-intent signals — queries visitors ran that found nothing — useful for spotting needed synonyms, redirects, or catalog gaps. The lookback window cannot exceed 92 days. Optionally scope to specific search configs.

Name	Type	Required	Description
`websiteUuid`	string	Yes	The UUID of the customer's website in Hello Retail. Use `getWebsiteInfo` to look up available websites, or find it in my.helloretail.com under Settings → Website Settings → Website Unique Id.
`startDate`	string	No	Start of the window, inclusive, ISO YYYY-MM-DD. Defaults to 30 days before endDate. Window must not exceed 92 days.
`endDate`	string	No	End of the window, inclusive, ISO YYYY-MM-DD. Defaults to today.
`keys`	string[]	No	Search-config UUIDs to scope to (from `listSearchConfigs`). Omit for all of the website's configs.
`limit`	integer	No	Maximum number of queries to return. Default 20, capped at 100.

Example request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "getTopSearchesWithoutResults",
    "arguments": {
      "websiteUuid": "<string>"
    }
  }
}

Returns

{
  "results": [
    {
      "query": "<string>",
      "filters": [],
      "searches": 0
    }
  ]
}

getSearchFilterUsage¶

List the most-used search filters for a customer website using Hello Retail, ranked by usage count. Each row is a field/value pair (e.g. brand = Nike) and how many times visitors applied it. Reveals which facets shoppers rely on. Optionally scope to specific search configs.

Name	Type	Required	Description
`websiteUuid`	string	Yes	The UUID of the customer's website in Hello Retail. Use `getWebsiteInfo` to look up available websites, or find it in my.helloretail.com under Settings → Website Settings → Website Unique Id.
`startDate`	string	No	Start of the window, inclusive, ISO YYYY-MM-DD. Defaults to 30 days before endDate.
`endDate`	string	No	End of the window, inclusive, ISO YYYY-MM-DD. Defaults to today.
`keys`	string[]	No	Search-config UUIDs to scope to (from `listSearchConfigs`). Omit for all of the website's configs.
`limit`	integer	No	Maximum number of filters to return. Default 20, capped at 100.

Example request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "getSearchFilterUsage",
    "arguments": {
      "websiteUuid": "<string>"
    }
  }
}

Returns

{
  "results": [
    {
      "field": "<string>",
      "value": "<string>",
      "uses": 0
    }
  ]
}

getSearchSortingUsage¶

List the most-used search sort options for a customer website using Hello Retail, ranked by usage count. Each row is a sort field plus direction (ascending/descending) and how many times visitors selected it. Optionally scope to specific search configs.

Name	Type	Required	Description
`websiteUuid`	string	Yes	The UUID of the customer's website in Hello Retail. Use `getWebsiteInfo` to look up available websites, or find it in my.helloretail.com under Settings → Website Settings → Website Unique Id.
`startDate`	string	No	Start of the window, inclusive, ISO YYYY-MM-DD. Defaults to 30 days before endDate.
`endDate`	string	No	End of the window, inclusive, ISO YYYY-MM-DD. Defaults to today.
`keys`	string[]	No	Search-config UUIDs to scope to (from `listSearchConfigs`). Omit for all of the website's configs.
`limit`	integer	No	Maximum number of sort options to return. Default 20, capped at 100.

Example request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "getSearchSortingUsage",
    "arguments": {
      "websiteUuid": "<string>"
    }
  }
}

Returns

{
  "results": [
    {
      "field": "<string>",
      "ascending": false,
      "uses": 0
    }
  ]
}