1. Using the Search and Recommendation API to create search experiences

Adding rules

You can use the widget.items.search.rule object to configure how you want Sitecore Search to treat certain result items. You can blacklist, boost, bury, include, and pin items and categories. Except for the pin rule, you must nest a filter object within the rule object to specify which items the rule applies to.

For the data model of this object, see the Search and Recommendation API reference.

Note

The rules you pass in an API request override the rules configured in Sitecore Search.

Boosting items into slots

To boost an item or category into slots, add a widget.items.search.rule.boost object. You must specify the product or category you want to boost and the slots you want them to appear in.

In this example,

  • You want to boost all items in the product category.

  • You want boosted items to appear in slots two and three of the search results.

The following code shows a sample request:

{
    "widget": {
        "items": [
            {
                "rfk_id": "rfkid_7",
                "entity": "content",
                "search": {
                    "content": {},
                    "rule": {
                        "boost": [
                            {
                                "filter": {
                                    "type": "eq",
                                    "name": "type",
                                    "value": "products"
                                },
                                "slots": [
                                    2,
                                    3
                                ]
                            }
                        ]
                    }
                }
            }
        ]
    },
    "context": {
        "locale": {
            "country": "us",
            "language": "en"
        },
        "user": {
            "uuid": "159871551-1g-i4-4x-1p-f5tdhddqwvywv7b9g2vy-1664852644904"
        }
    }
}

The following is the response to the request:

        {
            "rfk_id": "rfkid_7",
            "entity": "content",
            "content": [
                {
                    "description": "Premier Assure is designed...",
                    "id": "https___www_sitecore_com_activities",
                    "image": "https:imageurl/activities/gettyimages-699087272-hero.jpg?md=20220921T172222Z",
                    "image_type": "Image",
                    "image_url": "www.imageur.com",
                    "last_modified": "2022-10-19 20:57:04Z",
                    "source_id": "407033",
                    "subtitle": "Improve the quality of your Sitecore investment using a review-based approach.",
                    "title": "Premier Assure services: assuring confidence in your investment",
                    "type": "Knowledge Center",
                    "url": "https://www.sitecore.com/activities"
                },
                {
                    "description": "Sitecore CDP Connector for Responsys...",
                    "id": "https___www_sitecore_com_products_marketplace_tap_cdp_sitecore-cdp-connector-for-responsys",
                    "source_id": "388218",
                    "subtitle": null,
                    "title": "Sitecore CDP Connector for Responsys",
                    "type": "products",
                    "url": "https://www.sitecore.com/products/marketplace/tap/cdp/sitecore-cdp-connector-for-responsys"
                },
                {
                    "description": "Sitecore CDP Integration for Amazon Sagemaker...",
                    "source_id": "388218",
                    "subtitle": null,
                    "title": "Sitecore CDP Integration for Amazon Sagemaker",
                    "type": "products",
                    "url": "https://www.sitecore.com/products/marketplace/tap/cdp/sitecore-cdp-integration-for-amazon-sagemaker"
                },
                {
                    "description": "Related topicsResource hubPersonalizationEnable customer connections with your brand...",
                    "id": "https___www_sitecore_com_content-management",
                    "image": "https:imageurl/content-gettyimages-691574517-original2.jpg?md=20220107T002955Z",
                    "image_type": "Image",
                    "image_url": "https:imageurl/588D7FE5D8C&t=544x310",
                    "last_modified": "2022-05-25 19:52:23Z",
                    "source_id": "407033",
                    "subtitle": "Content fuels the digital experience in just about every industry.",
                    "title": "Content resources",
                    "type": "Knowledge Center",
                    "url": "https://www.sitecore.com/content-management"
                }
                ...
            ],
            "total_item": 5856,
            "limit": 10,
            "offset": 0
        }
    ],
    "dt": 109,
    "ts": 1669433189900
}

In the response content object, you can see product items in the second and third results items, that is, slots two and three.

Boosting items without slots

To boost an item or category without specifying a slot, use a widget.items.search.rule.boost object. You'll need to specify the product or category you want to boost and the weight by which you want to boost it.

In this example,

  • The visitor searches for the keyword content.

  • You want to boost all blogs by a weight of 5.

{
    "widget": {
        "items": [
            {
                "entity": "content",
                "rfk_id": "rfkid_7",
                "search": {
                    "content": {},
                    "rule": {
                        "boost": [
                            {
                                "weight": 4,
                                "filter": {
                                    "type": "eq",
                                    "name": "type",
                                    "value": "Blogs"
                                }
                            }
                        ]
                    },
                    "personalization": {
                        "fields": [
                            "title",
                            "type"
                        ]
                    },
                    "limit": 10,
                    "offset": 0,
                    "query": {
                        "keyphrase": "content"
                    }
                },
                "sources": [
                    "407033",
                    "408162"
                ]
            }
        ]
    },
    "context": {
        "locale": {
            "country": "us",
            "language": "en"
        },
        "user": {
            "uuid": "159871551-ye-l5-4u-1p-0z7apweb0jxcibpfzr40-1663129543566"
        }
    }
}

Blacklisting items

To blacklist a list of items or categories, add a search.rule.blacklist object. These items or categories never show up in the search results.

In this example, you want to blacklist all content of type other. The following code shows a sample request:

{
    "widget": {
        "items": [
            {
                "rfk_id": "rfkid_7",
                "entity": "content",
                "search": {
                    "content": {},
                    "rule": {
                        "blacklist": {
                            "filter": {
                                "type": "eq",
                                "name": "type",
                                "value": "other"
                            }
                        }
                    }
                }
            }
        ]
    },
    "context": {
        "locale": {
            "country": "us",
            "language": "en"
        },
        "user": {
            "uuid": "159871551-1g-i4-4x-1p-f5tdhddqwvywv7b9g2vy-1664852644904"
        }
    }
}

The following is the response to the request:

{
    "widgets": [
        {
            "rfk_id": "rfkid_7",
            "entity": "content",
            "content": [
                {
                    "description": "Discover top moments...",
                    "id": "https___www_sitecore_com",
                    "image": "https:imageurl.com/sitecore-home-hero-v01-052722_72dpi.jpg?md=20220627T124154Z",
                    "last_modified": "2022-11-18 16:46:12Z",
                    "source_id": "407033",
                    "subtitle": "Digital Experience Platform and Content Hub that apply the power of data science and marketing technology to shape your business around new possibilities.",
                    "title": "Turn consumers into fans",
                    "type": "Others",
                    "url": "https://www.sitecore.com"
                },
                {
                    "description": "It captures data...",
                    "id": "https___www_sitecore_com_blog_digital-transformation_7-business-benefits-of-a-customer-data-platform",
                    "image": "https:imageurl.com/gettyimages-1299625060_insights_feature.png?md=20220224T144643Z",
                    "image_url": "https://imageurl.com/79E042A6C3001AB18B&t=544x310",
                    "last_modified": "2022-04-05 04:57:22Z",
                    "product": "Customer Data Platform",
                    "source_id": "407033",
                    "subtitle": "From smashing data silos and building loyalty, to driving revenue, our blog explores 7 transformative business effects of a customer data platform.",
                    "title": "7 business benefits of a customer data platform",
                    "type": "Others",
                    "url": "https://www.sitecore.com/blog/digital-transformation/7-business-benefits-of-a-customer-data-platform"
                }, 

        ...
            ],
            "total_item": 4934,
            "limit": 10,
            "offset": 0
        }
    ],
    "dt": 30,
    "ts": 1669054635432
}

In the response content object, you can see that no item has a type of other.

Pinning items

To pin an item to a particular slot in the search results, use the search.rule.pin object and specify the slot you want to use and the ID of the item you want to pin.

In this example, you want to pin a blog about cloud computing to slot number two.

The following code shows a sample request:

{
    "widget": {
        "items": [
            {
                "rfk_id": "rfkid_7",
                "entity": "content",
                "sources": [
                    "388218",
                    "390565"
                ],
                "search": {
                    "content": {},
                    "rule": {
                        "pin": [
                            {
                                "slot": 2,
                                "id": "https___www_sitecore_com_blog_cloud_cloud-computing-in-business-and-the-future-of-cx"
                            }
                        ]
                    }
                }
            }
        ]
    },
    "context": {
        "locale": {
            "country": "us",
            "language": "en"
        },
        "user": {
            "uuid": "159871551-1g-i4-4x-1p-f5tdhddqwvywv7b9g2vy-1664852644904"
        }
    }
}

The following is the response to the request:

{
    "widgets": [
        {
            "rfk_id": "rfkid_7",
            "entity": "content",
            "content": [
                {
                    "description": "October 13, 2021...",
                    "id": "https___www_sitecore_com_company_news-events_news_2021_10_majority-of-mena-brands-changed-customer-experiences-due-to-the-pandemic",
                    "source_id": "388218",
                    "subtitle": null,
                    "title": "Khaleej Times: Majority of Mena brands changed customer experiences due to the pandemic",
                    "type": "news",
                    "url": "https://www.sitecore.com/company/news-events/news/2021/10/majority-of-mena-brands-changed-customer-experiences-due-to-the-pandemic"
                },
                {
                    "description": "Companies that survived...",
                    "id": "https___www_sitecore_com_blog_cloud_cloud-computing-in-business-and-the-future-of-cx",
                    "image_url": "https://imageurl/cloud-computing-in-business-and-the-future-of-cx/gettyimages-1209700460_heromedium_mb.jpg?mw=600&md=20211006T181735Z&hash=827DB91BE20225F7C4BEFDF36BDD0249&t=544x310",
                    "source_id": "388218",
                    "subtitle": "How CIOs can lead organizational transformation starting with marketing.",
                    "title": "Cloud computing in business and the future of CX",
                    "type": "blogs",
                    "url": "https://www.sitecore.com/blog/cloud/cloud-computing-in-business-and-the-future-of-cx"
                }, 

        ...
            ],
            "total_item": 2881,
            "limit": 10,
            "offset": 0
        }
    ],
    "dt": 52,
    "ts": 1669054542978
}

In the response content object, you see the blog you want as the second item in the search results, in slot number two.

If you have suggestions for improving this article, let us know!