Method Signature
getBrowseGroups(
parameters?: Pick<IBrowseParameters, 'filters' | 'section' | 'fmtOptions'>,
networkParameters?: NetworkParameters
): Promise<GetBrowseGroupsResponse>
Parameters
Additional parameters to refine the result setShow parameters properties
Key-value mapping of filters used to refine groups. Example: { group_id: "drill_collection" }
The section name for results
Format options used to refine result groupsShow fmtOptions properties
Maximum depth for nested groups. Controls how many levels of category hierarchy to return.
Parameters relevant to the network requestShow networkParameters properties
Request timeout in milliseconds
Returns
Returns a Promise that resolves to a browse groups response object.
Information about the request that was made, including applied filters and parameters
The browse groups data
Array of group objects representing categories or collections. Each group includes:
display_name: Human-readable name of the groupgroup_id: Unique identifier for the groupcount: Number of items in the groupdata: Additional metadata about the groupchildren: Nested child groups (if groups_max_depth > 1)
Information about result sources (tokens, embeddings, etc.)
Refined content and merchandising rules applied to groups
Unique identifier for this result set, used for analytics tracking
Examples
Basic Browse Groups
const groups = await constructorio.browse.getBrowseGroups();
console.log(groups.response.groups); // Array of all top-level groups
Browse Groups with Filters
const groups = await constructorio.browse.getBrowseGroups({
filters: {
group_id: 'drill_collection'
}
});
console.log(groups.response.groups);
Browse Groups with Nested Hierarchy
const groups = await constructorio.browse.getBrowseGroups({
fmtOptions: {
groups_max_depth: 2
}
});
// Access nested groups
groups.response.groups.forEach(group => {
console.log('Parent:', group.display_name);
if (group.children) {
group.children.forEach(child => {
console.log(' Child:', child.display_name);
});
}
});
Browse Groups with Deep Hierarchy
const groups = await constructorio.browse.getBrowseGroups({
fmtOptions: {
groups_max_depth: 3
},
section: 'Products'
});
// Navigate through multiple levels
const renderGroupTree = (groups, level = 0) => {
groups.forEach(group => {
console.log(' '.repeat(level) + group.display_name);
if (group.children) {
renderGroupTree(group.children, level + 1);
}
});
};
renderGroupTree(groups.response.groups);
Browse Groups with Custom Section
const groups = await constructorio.browse.getBrowseGroups({
section: 'Blog Posts',
fmtOptions: {
groups_max_depth: 1
}
});
Browse Groups with Timeout
const groups = await constructorio.browse.getBrowseGroups(
{
fmtOptions: {
groups_max_depth: 2
}
},
{
timeout: 5000 // 5 second timeout
}
);
Use Cases
Build a hierarchical navigation menu:
const groups = await constructorio.browse.getBrowseGroups({
fmtOptions: {
groups_max_depth: 3
}
});
// Render navigation
const buildNavigation = (groups) => {
return groups.map(group => ({
label: group.display_name,
href: `/browse/${group.group_id}`,
count: group.count,
children: group.children ? buildNavigation(group.children) : []
}));
};
const navigation = buildNavigation(groups.response.groups);
Category Landing Page
Display category information and subcategories:
const groups = await constructorio.browse.getBrowseGroups({
filters: {
group_id: 'power-tools'
},
fmtOptions: {
groups_max_depth: 2
}
});
if (groups.response.groups.length > 0) {
const category = groups.response.groups[0];
console.log('Category:', category.display_name);
console.log('Subcategories:', category.children);
}
Breadcrumb Navigation
Generate breadcrumb trails from group hierarchy:
const groups = await constructorio.browse.getBrowseGroups({
fmtOptions: {
groups_max_depth: 3
}
});
const findGroupPath = (groups, targetId, path = []) => {
for (const group of groups) {
const currentPath = [...path, group];
if (group.group_id === targetId) {
return currentPath;
}
if (group.children) {
const found = findGroupPath(group.children, targetId, currentPath);
if (found) return found;
}
}
return null;
};
const breadcrumbs = findGroupPath(groups.response.groups, 'cordless-drills');
Faceted Category Browser
Combine groups with additional filtering:
const groups = await constructorio.browse.getBrowseGroups({
filters: {
availability: 'in_stock',
brand: 'DeWalt'
},
fmtOptions: {
groups_max_depth: 2
}
});
// Display only groups with available products
const availableGroups = groups.response.groups.filter(
group => group.count > 0
);
Response Structure Details
Group Object
Each group in the groups array has the following structure:
{
display_name: string; // Human-readable name
group_id: string; // Unique identifier
count: number; // Number of items in group
data: { // Additional metadata
id: string;
[key: string]: any;
};
children?: Group[]; // Nested child groups
parents?: Group[]; // Parent groups (if applicable)
}
Error Handling
try {
const groups = await constructorio.browse.getBrowseGroups({
fmtOptions: {
groups_max_depth: 2
}
});
if (groups.response.groups.length === 0) {
console.log('No groups found');
} else {
console.log(`Found ${groups.response.groups.length} groups`);
}
} catch (error) {
console.error('Failed to fetch browse groups:', error);
}
Additional Resources
