Developer Guide
Visit our Knowledge BaseDeveloper CommunityRequest a Demo

Experience Search

Get the chosen variations for Semantic and Visual Search campaigns

Suggest Edits

Search API is a server-side API that enables personalized search for your website or app. It supports:

  • Semantic Search: A native AI-powered, multi-modal search solution that uses both image and text embedding to deliver highly relevant search results for text queries (for example, blue shoes).
  • Visual Search: An image-based search solution that enables users to search using images and retrieve visually similar or relevant products.

About the Search API

Search API includes the following parameters:

ParameterDescription
imageBase64/textThe user query to retrieve results for, either as a base64 image or as text.
For example, “Women's shoes” or an image of women's shoes. Learn more about sending queries
paginationDivide the search response into pages.
For example, get the most relevant results for slots 25 to 48 or for page 3. Learn more about pagination
filtersMatch results to user-specific filters.
For example, price is below $25 or gender is Men. Learn more about filtering
facetsRetrieve the relevant filters for the results, their possible values, and the count for each value. Learn more about facets
sortBySort results, either by relevance to the user query or by another product attribute.
For example, price, from low to high. Learn more about sorting

The API also includes the same attributes of the Choose endpoint of Experience API, supporting targeting and A/B testing variations of merchandizing rules and search logics. This requires you to add additional data, such as DYID, session ID, device attributes, and additional attributes that enable contextual targeting. Learn more about Choose requests.

Report Engagement

To enable tracking of clicks and purchases, you need to trigger an API call for every click on a search result item. These clicks will appear in reports and allow you to attribute purchases and other user interactions that occur after a search result is clicked. Learn more about engagement types

📌

Note

If Dynamic Yield is already implemented on your site and app, Purchase, Add to Cart, and other events automatically appear in your reports when you report Engagement.

If you’re new to Dynamic Yield, check out the Track User Interactions article.

Request example

{
  "query": {
    "text": "dress",
    "filters": [
      {
        "field": "categories",
        "values": ["dresses", "tops"]
      },
      {
        "field": "price",
        "min": 100,
        "max": 200
      }
    ],
    "pagination": {
      "numItems": 24,
      "offset": 0
    },
    "user": {
      "active_consent_accepted": true,
      "dyid": "12264556113"
    },
    "session": {
      "dy": "3124353434443123"
    },
    "context": {
      "page": {
        "type": "HOMEPAGE",
        "location": "https://shop.biz/nice-shirt-p76311.html",
        "referrer": "https://google.cz",
        "locale": "en_US"
      }
    },
    "selector": {
      "name": "Semantic Search"
    },
    "options": {
      "returnAnalyticsMetadata": false,
      "isImplicitClientData": false
    }
  }
}

Note: A Visual Search request follows the same structure, except it doesn't support pagination and usesimageBase64 instead of text.

Response example

{
  "id": 24,
  "name": "Visual Search",
  "type": "VISUAL_SEARCH_DECISION",
  "decisionId": "d29ybGQK",
  "variations": [
    {
      "id": 203,
      "payload": {
        "type": "SEARCH",
        "data": {
          "totalNumResults" : 50,
          "facets": [{
              "column": "color",            
              "valuesType": "string",
              "displayName": "Color",
              "values": [
                {
                  "name": "Black dark",
                  "count": 560
                },
                {
                  "name": "White dusty light",
                  "count": 191
                }
              ]
            }
          }],
          "slots": [
            {
              "slotId": "aGVsbG93b3JsZAo=",
              "sku": "SKU_C",
            },
            {
              "slotId": "d2VsY29tZWR1ZAo=",
              "sku": "SKU_A"
            },
            {
              "slotId": "d2VsY29tZWR1ZAo=",
              "sku": "SKU_B"
            }
          ]
        }
      }
    }
  ]
}

For the request structure and examples, see the API Reference.

Updated 5 days ago