Calling the Search and Recommendation API
In Sitecore Search, HTTPS protocol is required when using the Search and Recommendation API. The API accepts requests in JSON format.
API URL and methods
You can get the API URL in Sitecore Search, in the Developer Resources section, on the API Access tab.
Use the POST method to send requests to the Search and Recommendation API.
Authentication
You must authenticate to access Sitecore Search REST APIs. Use an API key or access token in the request header.
Mandatory objects
When you send requests to the API, you must include these objects to get a response:
-
rfk.domainId- add this to the header of your request to specify the domain for which you want to make the request. -
widget.items.rfkd_id- add this key to specify therfkidof the widget you want to call. -
widget.items.entity- add this key to specify the entity you want to use for this request. -
context.locale- If you have a multi-locale domain, add this object to specify the country and language you want to use for the results.
Recommended object
When you send requests to the API, we recommend that you add the following object:
-
context.user.uuid- an anonymous unique identifier of the visitor who visits the page. Add this object so that Sitecore Search can give your visitors relevant search results. If you do not pass the uuid, the search results you see are not tailored to that specific visitor. To learn how to generate a uuid, see Using a UUID to track site visitors.
If your custom UUID does not follow the above format, ensure that your custom free-form ID is passed in context.user.user_id instead of context.user.uuid in your Search request.
Sample request
The following is a sample POST request to the Search and Recommendation API to get content for the key phrase cloud computing:
{
"widget": {
"items": [
{
"rfk_id": "rfkid_7",
"entity": "content",
"search": {
"content": {},
"query": {
"keyphrase": "cloud computing"
}
}
}
]
},
"context": {
"locale": {
"country": "us",
"language": "en"
}
"user": {
"uuid": "string" //or "user_id": "string" if your uuid does not follow the example here (https://doc.sitecore.com/search/en/developers/search-developer-guide/using-a-uuid-to-track-site-visitors.html)"uuid": "string"
}
}
}