Skip to content

28. February 2025

Product family in Search (for developers)

To enable the display of product families in search results, we have added the ability to ingest product family information into the search index. This is useful when managing multi-level product families and wanting to show family details in search results. An example of a product family could be a product available in different sizes and colours (known in PIM as master/variant hierarchies).

Example of a PIM product family

Ingesting product family information

To ingest product family information into the search index, you need to include family details in the request model for the

/api/ingestion/segments/{segmentId}/products/create-or-patch

endpoint in the Admin API. Here is an example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
{
    "name": "Woolen socks",
    "shortDescription": "Some nice woolen socks",
    "longDescription": "Some very nice and warm woolen socks",
    "productNumber": "prod-1",
    "rating": 3.5,
    "activeFromUtc": "2000-01-01",
    "activeToUtc": "2200-01-01",
    "alternativeIds": [
        "MySocks-external"
    ],
    "alternativeSearchWords": [
        "Socks"
    ],
    "metadata": {
        "splash": "New"
    },
    "categories": [
        {
            "categoryPathElements": [
                {
                    "categoryId": "c-1",
                    "categoryName": "Women's socks"
                }
            ]
        }
    ],
    "media": [
        {
            "type": "Image",
            "url": "http://example.com/sock.jpg",
            "metadata": "600X400"
        }
    ],
    "familyModel": {
        "familyId": "my-colored-socks"
    },
    "productId": "my-socks"
}

In the example above, the familyModel object contains the familyId property, which is the unique identifier for the product family.

Showing product family information in the search results

When using the /search endpoint in the Search API, family information is included in the search results. Here is an example of how it is returned:

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
{
  "products": [
    {
      "id": "my-socks",
      "alternativeIds": [
        "MySocks-external"
      ],
      "productNumber": "prod-1",
      "name": "Woolen socks",
      "shortDescription": "Some nice woolen socks",
      "longDescription": "Some very nice and warm woolen socks",
      "media": [
        {
          "url": "https://my-image-url.jpg",
          "type": "Image",
          "metadata": "600X400"
        }
      ],
      "metadata": {
        "splash": "New"
      },
      "categories": [
        [
          {
            "name": "Toys or car parts",
            "id": "cat-toys-1"
          }
        ]
      ],
      "family": {
        "familyId": "my-socks",
        "totalSiblings": 1,
        "siblings": [
          {
            "productId": "my-socks",
            "productName": "Woolen socks",
            "media": "https://my-image-url.jpg"
          }
        ]
      },
      "skus": [
        {
          "id": "my-socks-42",
          "skuNo": "xs",
          "ean": "0012345678905",
          "name": "Red Paint",
          "metadata": {
            "splash": "New"
          },
          "price": {
            "price": 90,
            "listPrice": 100
          },
          "stringAttribute": null,
          "numberAttributes": null,
          "intervalAttributes": null
        }
      ]
    }
  ],
  "facets": [
    {
      "key": "color",
      "name": "Color",
      "facetType": "Term",
      "max": 30.6,
      "min": 10.1,
      "selectedTo": 20.3,
      "selectedFrom": 15.4,
      "values": [
        {
          "count": 30,
          "isSelected": false,
          "key": "green",
          "value": "Green"
        }
      ],
      "match": "any"
    }
  ],
  "suggestions": [
    "Shorts for women"
  ],
  "didYouMean": [
    "Shorts for women"
  ],
  "relatedTags": [
    {
      "tag": "…",
      "suggestionPhrase": "…"
    }
  ],
  "numberOfRequestedProductResults": 1,
  "totalProducts": 1,
  "totalSkus": null,
  "totalSuggestions": 1,
  "totalRelatedTags": 1,
  "originalPhrase": null,
  "usedPhrase": null,
  "productOffset": 0,
  "numberOfRequestedContentResults": 1,
  "totalContent": 1,
  "content": [
    {
      "contentId": "my-page",
      "path": "…",
      "name": "…",
      "shortDescription": "…",
      "media": [
        {
          "type": "Image",
          "url": "http://example.com/sock.jpg",
          "metadata": "600X400"
        }
      ],
      "stringAttribute": null,
      "numberAttributes": null,
      "metadata": {
        "splash": "New"
      }
    }
  ],
  "explanation": [
    {
      "description": null,
      "details": [
        {
          "description": null,
          "details": [

          ]
        }
      ]
    }
  ]
}

Note

Please note that the number of siblings returned in the search results is controlled by the scope.

Number of siblings is controlled by the scope
Number of siblings is controlled by the scope

You can find more information about family data in the Search documentation.