search mobile facets autocomplete spellcheck crawler rankings weights synonyms analytics engage api customize documentation install setup technology content domains user history info home business cart chart contact email activate analyticsalt analytics autocomplete cart contact content crawling custom documentation domains email engage faceted history info install mobile person querybuilder search setup spellcheck synonyms weights engage_search_term engage_related_content engage_next_results engage_personalized_results engage_recent_results success add arrow-down arrow-left arrow-right arrow-up caret-down caret-left caret-right caret-up check close content conversions-small conversions details edit grid help small-info error live magento minus move photo pin plus preview refresh search settings small-home stat subtract text trash unpin wordpress x alert case_deflection advanced-permissions keyword-detection predictive-ai sso

Curations Guide

You are the curator of your Engine. You are in control of how documents are consumed by your visitors. When users perform search queries, you can configure a curation so that they discover what you would most like them to discover. Or, what you would not like them to discover.

There are two curation parameters:

  • Promoted: Promote specific documents to have them appear in a prominent way. You can promote multiple documents per query, the array order representing the order in which they will appear.
  • Hidden: Hide specific documents so that they do not appear. You can hide multiple documents per query, the array order being unimportant because... they are hidden.

Consider an example where your users are searching for "kettle". You might promote a specific kettle. Perhaps it is the most popular one, the one a visitor is most likely to purchase. Or, you could hide a kettle - maybe it is out-of-stock or having issues - to prevent people from seeing it.

Each set of curations belongs to a query. A query may only be part of one curation set.

There are two ways to build a curation set: using the Curations UI within the dashboard or through the Curations API.

Curation changes are live and propagated once saved.
No re-indexing is required! The changes are reflected immediately.

Curations UI

Each Engine contains a Curations UI. This will allow any stakeholder, developer or otherwise, to curate result sets.

To begin, click into Curations.

Curations - A view without curations.
The empty view when you first click within Curations.

From there, click on Create new Curation. You can provide one or more queries. The idea of a Curation is to curate the result set of a given query. And so, we must supply the query first to receive its result set. You can enter one, or multiple queries. In this case, we want to curate the results for the "mountains" query.

Curations - Enter a query to curate its result set.
A textbox, wherein you can enter a query to curate. There is a multi query slider, if you want to curate multiple queries.

Once at least one query has been provided, results of that query will appear as a list of organic results. Organic results have nothing promoted and nothing hidden, they reflect the current result set for that query.

Curations - The organic query appears. Organic queries do not have any hidden or promoted items.
The curations view will gather the top organic results for your provided query. You can then promote or hide results within the set.

Now, to promote a result. We want Rocky Mountain National Park to be the first result when a user queries for "mountains". We can either click the star, or drag the result up by clicking on the drag handle on the far left. We can promote multiple documents and rearrange the order of our promoted documents. If we promoted 3 documents, we can order them however we would like. Click Demote All to return all promoted results back to the organic result set.

Curations - Promoting a result. You can drag and drop, or click the star.
The Rocky Mountain Park document has been promoted. It will now be the top result for the

It appears Mesa Verde National Park is closed for maintenance. We should hide the document so that it no longer appears within the result set. To do so, click on the eye icon.

Curations - Hiding a result. Click the eye icon.
Promoting a result

All hidden documents collapse underneath the organic results in their own section. You can view your hidden results, and unhide them by clicking Restore All.

Curations - Hidden documents collapse underneath the organic result set.
Promoting a result

If you chose multiple queries, or want to curate another query, you can curate them by clicking Manage Queries. From there, one can add or select a new query. Selecting a query changes the result set to match that query. This can be used to curate result sets for similar concepts that are not synonyms, like "big mountains", "small mountains", "mounds", and so on.

Curations - Curate different queries together if they share a logical thread.
Promoting a result

The moment you promote or hide a document, the new result set will be active. Anyone who uses the query that you have curated will receive your newly minted result set. You can Restore Defaults to revert all of your changes, or delete the curation from the main curations view.

Curations API

The App Search API provides full control over Curations. When you craft a curation you must include one or more queries within an array. That array of potential queries, along with the documents that fit the promoted and hidden parameters, form a curation.

In this way, users who query for banana, bananana, bonana and nanner will receive the same promoted items and not receive the same hidden items. This set, this grouping, is considered a curation with its own unique identifier.

The id of a curation is serialized via BSON. The id of a document is serialized via BSON as well, but you can supply your own id value. A response might look something like this:

{
  "id": "cur-a5b6c7",
  "queries": [
    "banana", "bananana", "bonana", "nanner"
  ],
  "promoted": [
    "doc-123", "doc-a2b3c4", "doc-456"
  ],
  "hidden": [
    "doc-a9b87c", "doc-789", "doc-a7b6c5"
  ]
}

With this extra context, you are ready for the Curations API Reference.

Helpful Reads

Your Curations can become mighty tools in improving the relevance, and thus the overall experience, of search queries. Business goals, too, as you can get your visitors where you would like them to be. If you want to take a deep look into how users are interacting with your engines, the Analytics and Clickthrough endpoints are worth exploring. You could also brush up on the basics within our Search Guide.


Stuck? Looking for help? Contact support or check out the App Search community forum!