Test a search request using the API Explorer
You can use the API Explorer tab on the Developer Resources page of Sitecore Search to build a JSON request and fetch data using the Search and Recommendation API endpoint.
This walkthrough describes how to:
-
Build a request.
-
View the request.
-
Run the request and copy the response.
Build a request
This section describes how to build a request using the left-hand pane of the API Explorer. Alternatively, you can paste a request data object directly into the Request pane and click Build.
To build a request pane:
-
On the menu bar, click Developer Resources and then click on the API Explorer tab.
-
In the left-hand pane, in the Page drop-down menu, to select the page you want to test, click its name.
TipIf you want to clear a previously built request, in the left-hand pane, click Reset.
-
(Optional) To restrict the response to one or more widgets, click the Widget field and then on the drop-down list that appears, select or deselect widgets. Widgets belonging to the selected page are pre-selected.
-
In the Entity drop-down menu, click on an entity.
-
For the optional fields listed in the following table, provide values as described.
Field
Description
Source
To restrict results from specific sources, select them.
Limit
To limit the number of results, enter value.
Offset
To skip results, enter number to skip.
-
For the optional sections listed in the following table, provide values as described.
Section
Description
Locale
If your domain uses multiple locales, in the Country & Language drop-down menu, click a country and language.
NoteIf do not select a locale, the default domain locale is used.
Query
In the Query section, you can configure to highlight certain words in the results. You can even add HTML tags to format the words or modify behavior, for example, interactivity.
To highlight keywords in the results, do all of the following:
-
In the Keywords field, enter keywords.
-
In the Highlight in attribute drop-down menu, click attribute.
-
In the Highlight fragment size field, enter maximum characters to highlight.
-
In the Highlight tag fields, to add HTML tags before and after highlighted text, enter tags.
Suggestion blocks
Preview search widgets can display suggestions as a visitor types keywords in the search input field.
To add a suggestion block, do all of the following:
-
Click
Add Suggestion Block and then select a block. -
In the block, to limit the number of suggestions, in the Max field, enter maximum count.
Context/IDs
You can specify indexed items as context for your query. For example, use Product A as context in a recommendation widget for co-bought products.
To add an entity, do all of the following:
-
Click
Add Entity then select an entity. -
In the input field of the entity, to return specific indexed items, enter their ID.
NoteIn the Content Collection section, you can browse your indexed items for their IDs.
Context/User
Personalization and relevance are core features of Search. In the API Explorer, all requests require information about the visitor or user.
To provide a visitor or user as context, do one of the following, depending on your implementation:
-
In the UUID field, enter the ID assigned to a visitor or user by Sitecore.
-
In the User ID field, enter the ID you have assigned to the visitor or user.
NoteIn the Content Collection section, you can browse your visitors for their IDs.
Optionally, to provide a user groups as context, in the User groups field, enter the IDs of the user groups associated with to the visitor or user.
Facet
To specify facets, do all of the following as needed:
-
To fetch results for all facts, select the All check box.
-
In the Max field, to restrict the number of facet values, enter the maximum number. Default is 100. However, for testing purposes, we recommend limiting this number further.
-
In the Sort drop-down menu, click Text or Count.
-
To include a specific facet, click
Add Facet, then select a facet, and then for the selected facet, do the following as needed:-
In the UUID field, enter the ID assigned to a visitor or user by Sitecore.
-
In the Max field, to restrict the number of facet values, enter the maximum number. Default is 100. However, for testing purposes, we recommend limiting this number further.
-
In the Sort drop-down menu, click Text or Count.
-
Sort
To specify sorting options, do the following:
-
In the Select drop-down menu, click a sorting option.
-
To fetch the list of all sorting options, select the Return All Sort Choices check box.
-
-
Click Build. The request appears in the Request panel.
View the request
After you build a request, you should check for errors by examining the output in the Request pane. If there are any missing required keys, a warning appears above the JSON output.
To view the request:
-
Read the request in JSON format in the Request pane.
TipIf the generated request is incorrect, you can fix it by entering different values in the Build pane and then clicking Build again. Alternatively, you can directly edit the JSON in the Request pane.
-
Optionally, to copy the request, click Copy to clipboard as...
and then click your preferred format.NoteYou can copy the request as a data object or as a cURL object using a Sitecore host or your subdomain.
Run the request and copy the response
After creating a request, run it to make sure it is being sent correctly and that there are no errors.
To run the request and copy the response:
-
In the Request pane, click Run.
-
Read the response in JSON format in the Response pane of the API Explorer. You can scaffold and scroll through the response.
-
Click Copy to clipboard as...
and click Copy as data object.