Pre-search Suggestions

Fetch and render curated Pre-search Suggestions before a visitor starts typing in a custom search UI.

Pre-search Suggestions are curated search terms configured in MyCludo. Use them to show helpful suggestions in an empty search input, before the visitor starts typing.

This guide shows API-only customers how to read the configured terms from the same public settings endpoint used by CludoJS.

Prerequisites

From MyCludo, collect the values for the engine where Pre-search Suggestions are configured:

Value	Description
Customer ID	The customer ID for your Cludo account
Engine ID	The engine where suggestions were configured
Search key	The public search or site key for the engine
Region	EU customers use https://api.cludo.com; US customers use https://api-us1.cludo.com

The feature must also be enabled on your subscription. If Tools > Pre-search Suggestions in MyCludo lets you save terms, the feature is enabled.

Step 1: Build the SiteKey authorization header

The request uses SiteKey authentication. Build the token by Base64-encoding {customerId}:{engineId}:{searchKey}:

Authorization: SiteKey <base64("{customerId}:{engineId}:{searchKey}")>

Step 2: Call the public settings endpoint

Fetch the website public settings for the engine:

curl https://api.cludo.com/api/v3/{customerId}/{engineId}/websites/publicsettings

Use the regional base URL that matches your customer ID:

Customer ID	Region	Base URL
Below 10,000,000	EU	https://api.cludo.com
10,000,000 and above	US	https://api-us1.cludo.com

Step 3: Parse instantSuggestionsConfiguration

The response contains many website settings. The Pre-search Suggestions field is instantSuggestionsConfiguration.

This field is returned as a JSON-encoded string, so parse the response JSON first, then parse instantSuggestionsConfiguration a second time:

{
  "suggestions": ["popular term 1", "popular term 2", "popular term 3"],
  "showRecentSearches": true,
  "limit": 5
}

Field	Description
suggestions	Curated terms entered in MyCludo, returned in display order
limit	Maximum number of items to show
showRecentSearches	Whether your UI should also show the visitor’s recent searches

Cludo does not store recent searches for the visitor. If showRecentSearches is true, store and merge recent searches client-side, for example in localStorage.