Method Signature
constructorio.recommendations.getRecommendations(podId, parameters, networkParameters)
Parameters
The unique identifier of the recommendation pod configured in your Constructor.io dashboard.
Optional parameters to refine recommendation results.The number of results to return. Defaults to the pod configuration.
Item ID(s) to retrieve recommendations for. Used by strategy-specific pods like “similar items” or “frequently bought together”.Can be a single item ID string or an array of item IDs.
The section to return results from. Useful for filtering recommendations to specific catalog sections.
A search term to refine results. Strategy-specific parameter used by certain recommendation types.
Key-value pairs of filters to refine results. Filter keys correspond to facet names in your Constructor.io catalog.{
brand: 'Nike',
color: ['red', 'blue'],
price: { min: 10, max: 100 }
}
Object to aggregate variations of the same item. See Variations Mapping for details.{
group_by: [
{ name: 'product_id', field: 'data.product_id' }
],
values: {
size: { aggregation: 'all', field: 'data.facets.size' }
}
}
parameters.preFilterExpression
Faceting expression to scope recommendation results. See Collections for details.{
or: [
{ and: [{ name: 'group_id', value: 'electronics' }] },
{ and: [{ name: 'category', value: 'accessories' }] }
]
}
Options to format different aspects of the response. See API Reference for details.{
groups_max_depth: 2,
groups_start: 'current'
}
Array of hidden metadata field names to return in the response.['hidden_metadata_field_1', 'hidden_metadata_field_2']
Optional parameters for the network request.networkParameters.timeout
Request timeout in milliseconds.
Returns
Promise<RecommendationsResponse>
A promise that resolves to a recommendations response object.Echo of the request parameters sent to the API.The pod identifier from the request.
The number of results requested.
Item ID(s) from the request (if provided).
Filters applied to the request.
The recommendations response data.Array of recommendation result items.The unique item identifier.
The item’s metadata and attributes. Structure depends on your catalog configuration.Common fields include id, title, description, image_url, url, price, and custom metadata fields.
response.results[].matched_terms
Terms that were matched for this result (if applicable).
response.results[].is_slotted
Whether this result is a slotted/sponsored item.
response.results[].labels
Labels associated with this result item.
response.results[].strategy
Information about the recommendation strategy that surfaced this item.response.results[].strategy.id
The strategy identifier (e.g., best_sellers, similar_items).
response.results[].result_id
The result ID for tracking purposes. This ID should be used when tracking interactions with this result.
response.total_num_results
Total number of results returned.
Information about the recommendation pod.response.pod.display_name
The human-readable pod name.
Unique identifier for this set of results. Use this when tracking user interactions with recommendations.
Examples
Basic Recommendations
Get recommendations from a simple pod:
const ConstructorIO = require('@constructor-io/constructorio-client-node');
const constructorio = new ConstructorIO({
apiKey: 'YOUR_API_KEY',
apiToken: 'YOUR_API_TOKEN'
});
const results = await constructorio.recommendations.getRecommendations(
'best-sellers-pod'
);
console.log(results.response.results);
Recommendations with Number of Results
Limit the number of recommendations returned:
const results = await constructorio.recommendations.getRecommendations(
'trending-products',
{
numResults: 5
}
);
Item-Based Recommendations
Get recommendations based on a specific item (e.g., “similar items”):
const results = await constructorio.recommendations.getRecommendations(
'similar-items-pod',
{
itemIds: 'product-123',
numResults: 6
}
);
Multiple Item IDs
Get recommendations based on multiple items:
const results = await constructorio.recommendations.getRecommendations(
'frequently-bought-together',
{
itemIds: ['product-123', 'product-456'],
numResults: 4
}
);
Filtered Recommendations
Apply filters to refine recommendations:
const results = await constructorio.recommendations.getRecommendations(
'best-sellers-pod',
{
numResults: 10,
filters: {
category: 'electronics',
brand: ['Sony', 'Samsung'],
price: { min: 100, max: 1000 }
}
}
);
Section-Specific Recommendations
Get recommendations from a specific catalog section:
const results = await constructorio.recommendations.getRecommendations(
'homepage-recommendations',
{
section: 'Products',
numResults: 12
}
);
Recommendations with Hidden Fields
Include hidden metadata fields in the response:
const results = await constructorio.recommendations.getRecommendations(
'best-sellers-pod',
{
numResults: 8,
hiddenFields: ['internal_id', 'cost_price']
}
);
With Variations Mapping
Aggregate product variations:
const results = await constructorio.recommendations.getRecommendations(
'best-sellers-pod',
{
numResults: 10,
variationsMap: {
group_by: [
{ name: 'product_id', field: 'data.product_id' }
],
values: {
size: { aggregation: 'all', field: 'data.facets.size' },
color: { aggregation: 'all', field: 'data.facets.color' }
}
}
}
);
With Pre-Filter Expression
Scope results using a faceting expression:
const results = await constructorio.recommendations.getRecommendations(
'recommended-for-you',
{
numResults: 10,
preFilterExpression: {
or: [
{ and: [{ name: 'category', value: 'electronics' }] },
{ and: [{ name: 'category', value: 'accessories' }] }
]
}
}
);
With Network Timeout
Set a custom timeout for the request:
const results = await constructorio.recommendations.getRecommendations(
'best-sellers-pod',
{
numResults: 10
},
{
timeout: 5000 // 5 seconds
}
);
Complete Example with Multiple Parameters
const results = await constructorio.recommendations.getRecommendations(
'personalized-recommendations',
{
numResults: 12,
section: 'Products',
filters: {
brand: 'Nike',
category: ['shoes', 'apparel'],
in_stock: true
},
variationsMap: {
group_by: [
{ name: 'product_id', field: 'data.product_id' }
],
values: {
size: { aggregation: 'all', field: 'data.facets.size' }
}
},
hiddenFields: ['supplier_id']
},
{
timeout: 3000
}
);
// Process results
results.response.results.forEach(item => {
console.log(item.data.title, item.data.price);
console.log('Strategy:', item.strategy.id);
console.log('Result ID:', item.result_id);
});
Error Handling
try {
const results = await constructorio.recommendations.getRecommendations(
'my-pod',
{ numResults: 10 }
);
console.log(results.response.results);
} catch (error) {
if (error.message.includes('podId is a required parameter')) {
console.error('Pod ID is missing or invalid');
} else if (error.message.includes('malformed')) {
console.error('Unexpected response format from API');
} else {
console.error('Failed to get recommendations:', error.message);
}
}
Notes
- The
podId parameter is required and must be a non-empty string
- Each result item includes a
result_id that should be used for tracking user interactions
- Strategy-specific parameters (like
itemIds and term) may only work with certain pod configurations
- Filters are applied server-side and depend on your catalog’s facet configuration
- The response structure may include additional fields depending on your catalog configuration
