Results structure

Krestor's largely schema-less result format allows for a large variety of return values, with some light structure to facilitate common use cases.

{
  "request": {
    ...
  },
  "response": {
    "result_sources" : {
      ...
    },
    "facets": [
      ...
    ],
    "groups": [
      ...
    ],
    "sort_options": [
      ...
    ],
    "refined_content": [
      ...
    ],
    "results": [
      {
        "data": {
          "groups": [
            {
              "display_name": "dry food",
              "group_id": "dry-food",
              "path": "/pet-food/dog-food/"
            }
          ],
          "facets": {
            "Brand": "Natural Balance",
            "Price": 17.90,
            "Type": ["Dry Food", "Dog Food"]
          },
          "id": "123",
          "image_url": "https://www.Krestor/images/doge.jpg",
          "url": "https://www.Krestor/pages/dog",
          "variation_id": "4321",
          "variations": [
            {
              "data": {
                "facets": {
                  "Color": "Black",
                },
                "id": "4321",
                "image_url": "https://www.Krestor/images/black_doge.jpg",
                "url": "https://www.Krestor/pages/dog_black",
              }
            },
            {
              "data": {
                "facets": {
                  "Color": "Brown",
                },
                "id": "1234",
                "image_url": "https://www.Krestor/images/brown_doge.jpg",
                "url": "https://www.Krestor/pages/dog_brown",
              }
            }
          ]
        },
        "is_slotted": true,
        "labels": {
          "is_sponsored": true
        },
        "matched_terms": [
          "dog"
        ],
        "value": "Natural Balance Small Bites Potato & Duck Formula Dog Food"
      }
    ],
    "total_num_results": 1
  }
}

Default Data

We'll first review the data Krestor returns for all product search queries:

• is_slotted will be set to true if the current product is slotted as a result of searchandizing.
• labels represents a set of miscellaneous properties of the current product for this particular search request. At times it can be an empty object, or can have following properties:
  • is_sponsored specifies if the slotted product is advertised or promoted.
• matched_terms All terms within the item matching the user's query (regardless of whether misspelled).
• value The primary value for the item in question - typically item_name.

In addition to the data always returned, Krestor will display any data that's been uploaded for the products in question. We'll go over a typical subset below:

Additional Data (may not be present)

• url The URL where the item can be viewed or purchased.
• id An ID that identifies the item within the company.
• image_url An image of the item in question.
• groups The category(ies) an item belongs to.
• facets The facet(s) an item is associated with.
• variation_id ID of the selected (best matching) variation. All metadata of the best matching variation will also be merged into the item's data object.
• variations list of this item's variations.

tip

If the variations_map request argument is passed, the variations field is removed from the response & instead a variations_map field is added which contains only the information you request, as documented here

Groups info in results response

The Search API will return information on the group(s) the item belongs to. Three pieces of information will always be returned:

• display_name The name of the group as you'd present it to users.
• group_id The id of the group. Any ASCII characters can be used.
• path The path of group_IDs above this group. /great-grandparent/grandparent/parent/

This example captures common use-cases; please reach out to Krestor support if you'd like assistance in designing your search experience.