Groups Structure

Groups are typically used to indicate high-level categories for products. Each browse request will return all groups associated with items in the result set.

Flat group listings#

{
"request": {
...
},
"response": {
"facets": [
...
],
"groups": [
{
"children": [],
"count": 33,
"display_name": "Baby Care Products",
"group_id": "baby_care_products",
"parents": []
},
{
"children": [],
"count": 11,
"display_name": "Beverages",
"group_id": "beverages",
"parents": []
},
],
"sort_options": [
...
],
"results": [
...
],
"total_num_results": 44
}
}

If the index browsed just has a flat group hierarchy, a flat array of groups is returned, with empty arrays for children and parents fields.

Notice in this example that total_num_results is the sum of the count for each group. In this example, no products are a member of more than one group.

Groups fields#

field_nameAlways present?Description
display_nameYesThe name of the group as you'd present it to users.
group_idYesThe id of the group. Any ASCII characters can be used.
childrenNot when group is in parents arrayAn array of groups that are 'children' of the group in question i.e. hierarchically below. Empty if no children.
countNot when group is in parents arrayThe number of item results within the group that match the browse request.
parentsNot when group is in children arrayThe group_id of any parents. Empty for top-level categories.

Hierarchical group listings#

{
"request": {
...
},
"response": {
"facets": [
...
],
"groups": [
{
"children": [
{
"children": [],
"count": 2,
"display_name": "Baby Hair Brushes",
"group_id": "baby_hair_brushes",
"parents": []
},
{
"children": [],
"count": 3,
"display_name": "Diapers",
"group_id": "diapers",
"parents": []
}
],
"count": 5,
"display_name": "Baby Care Products",
"group_id": "baby_care_products",
"parents": []
},
{
"children": [],
"count": 5,
"display_name": "Beverages",
"group_id": "beverages",
"parents": []
},
],
"sort_options": [
...
],
"results": [
...
],
"total_num_results": 10
}
}

If an index has a hierarchy of groups, we return the full list of groups with results matching the browse request, with children groups returned within the children array of their parent group.

Notice in this example that the count for parent category Baby Care Products is the sum of its children, and total_num_results is the sum of the count for each top-level group. In this example, no products are a member of more than one group.