Skip to main content
Generates item recommendations using vector embeddings and collaborative filtering. This endpoint supports multiple recommendation strategies including similar items, diverse recommendations, and user history-based recommendations. 
POST https://api.worqhat.com/db/recommend

​
What Does This Endpoint Do?

This endpoint uses AI-powered recommendation algorithms to suggest relevant items to users. It combines vector embeddings with collaborative filtering techniques to provide personalized recommendations that go beyond simple similarity matching.

​
When to Use Recommendations

You’ll find this endpoint useful when you need to:
  • Build recommendation systems: Create “Recommended for you” features for e-commerce, content platforms, or any application with items
  • Personalize user experience: Show users items they’re likely to be interested in based on their behavior
  • Increase engagement: Help users discover new content or products they might like
  • Implement diverse recommendations: Avoid filter bubbles by showing varied suggestions
  • Handle cold start problems: Provide recommendations even for new users with limited history
  • Cross-sell and upsell: Suggest complementary or higher-value items

​
How It Works

  1. You provide a table and optionally a source item or user history
  2. The system analyzes vector embeddings and user interaction patterns
  3. It applies the specified recommendation strategy (similar, diverse, or popular)
  4. Results are returned with similarity scores and strategy metadata

​
Code Examples

​
Example 1: Item-to-Item Recommendations

This example shows how to generate recommendations based on a specific item.
  • Node.js
  • Python
  • Go
  • cURL
import Worqhat from 'worqhat';

// Initialize the client with your API key
const client = new Worqhat({
  apiKey: process.env.WORQHAT_API_KEY, // Always use environment variables for API keys
});

async function getItemRecommendations() {
  try {
    // Call the recommend method
    const response = await client.db.recommend({
      table: "products",
      record_id: "123",
      strategy: "similar",
      limit: 10,
      environment: process.env.WORQHAT_ENVIRONMENT || 'production' // Defaults to production
    });
    
    // Handle the successful response
    console.log(`Generated ${response.recommendations.length} recommendations`);
    console.log('Strategy used:', response.strategy);
    response.recommendations.forEach((rec, index) => {
      console.log(`${index + 1}. ${rec.record.name} (Similarity: ${rec.similarity})`);
    });
    return response;
  } catch (error) {
    // Handle any errors
    console.error('Error generating recommendations:', error.message);
  }
}

// Call the function
getItemRecommendations();

​
Example 2: User History-Based Recommendations

This example shows how to generate recommendations based on a user’s interaction history.
  • Node.js
  • Python
  • Go
  • cURL
import Worqhat from 'worqhat';

// Initialize the client with your API key
const client = new Worqhat({
  apiKey: process.env.WORQHAT_API_KEY,
});

async function getUserRecommendations() {
  try {
    // Generate recommendations based on user history
    const response = await client.db.recommend({
      table: "products",
      user_history: ["123", "456", "789"], // User's interaction history
      strategy: "similar",
      limit: 15,
      exclude_ids: ["123", "456"], // Exclude items user already interacted with
      environment: process.env.WORQHAT_ENVIRONMENT || 'production' // Defaults to production
    });
    
    // Handle the successful response
    console.log(`Generated ${response.recommendations.length} personalized recommendations`);
    response.recommendations.forEach((rec, index) => {
      console.log(`${index + 1}. ${rec.record.name} (Similarity: ${rec.similarity})`);
    });
    return response;
  } catch (error) {
    console.error('Error generating user recommendations:', error.message);
  }
}

getUserRecommendations();

​
Example 3: Diverse Recommendations

This example shows how to generate diverse recommendations to avoid filter bubbles.
  • Node.js
  • Python
  • Go
  • cURL
import Worqhat from 'worqhat';

// Initialize the client with your API key
const client = new Worqhat({
  apiKey: process.env.WORQHAT_API_KEY,
});

async function getDiverseRecommendations() {
  try {
    // Generate diverse recommendations
    const response = await client.db.recommend({
      table: "articles",
      user_history: ["art_1", "art_2", "art_3"],
      strategy: "diverse",  // Use diverse strategy
      limit: 20,
      environment: process.env.WORQHAT_ENVIRONMENT || 'production' // Defaults to production
    });
    
    // Handle the successful response
    console.log(`Generated ${response.recommendations.length} diverse recommendations`);
    console.log('Strategy used:', response.strategy);
    response.recommendations.forEach((rec, index) => {
      console.log(`${index + 1}. ${rec.record.title} (Similarity: ${rec.similarity})`);
    });
    return response;
  } catch (error) {
    console.error('Error generating diverse recommendations:', error.message);
  }
}

getDiverseRecommendations();

​
Request Body Explained

​
table
string
required
Table to generate recommendations from.Example: “products”
​
record_id
string|number
Source item ID for item-to-item recommendations. Use this OR user_history, not both.Example: “123”
​
user_history
array
Array of record IDs the user has interacted with. Use this OR record_id, not both.Example: [“123”, “456”, “789”]
​
strategy
string
Recommendation strategy to use. Options: “similar”, “diverse”, “popular”. Default: “similar”.
  • similar: Find items similar to source or user history
  • diverse: Find varied items to avoid filter bubbles
  • popular: Find popular items across all users
​
limit
number
Maximum number of recommendations to return. Range: 1-100, default: 10.
​
exclude_ids
array
Record IDs to exclude from recommendations (e.g., items user already has).Example: [“123”, “456”]

​
Response Fields Explained

​
success
boolean
true if recommendations were generated successfully, false otherwise.
​
recommendations
array
Array of recommended items, each containing:
  • record: The actual record data
  • similarity: Similarity score (0-1) indicating recommendation strength
  • _meta: Additional metadata including strategy and source information
​
strategy
string
Strategy used for generating recommendations.
​
executionTime
number
Recommendation generation time in milliseconds.

​
Example Response

{
  "success": true,
  "recommendations": [
    {
      "record": {
        "id": "456",
        "name": "Smart Home Hub",
        "description": "Central control unit for automated home systems",
        "category": "electronics",
        "price": 199.99
      },
      "similarity": 0.823,
      "_meta": {
        "strategy": "similar",
        "source": "single_item"
      }
    },
    {
      "record": {
        "id": "789",
        "name": "AI Voice Assistant",
        "description": "Intelligent voice-controlled device for home automation",
        "category": "electronics",
        "price": 149.99
      },
      "similarity": 0.756,
      "_meta": {
        "strategy": "similar",
        "source": "single_item"
      }
    }
  ],
  "strategy": "similar",
  "executionTime": 189
}

​
Common Errors and How to Fix Them

ErrorCauseSolution
”Table not found”The specified table doesn’t existCheck your table name for typos
”No embeddings found”The table doesn’t have vector embeddingsEnsure your table has been processed for embeddings
”Record not found”The specified record_id doesn’t existCheck that the record ID exists in the table
”Invalid strategy”The strategy value is not supportedUse one of: “similar”, “diverse”, “popular"
"No user history provided”Neither record_id nor user_history was providedProvide either a record_id or user_history array
”Unauthorized”Invalid or missing API keyCheck that you’re using a valid API key

​
Tips for Better Recommendations

  • Use appropriate strategies:
    • similar: For “More like this” features
    • diverse: To avoid filter bubbles and show variety
    • popular: For trending or top items
  • Exclude already-interacted items: Use exclude_ids to avoid recommending items users already have
  • Combine strategies: Use different strategies for different sections of your app
  • Monitor similarity scores: Higher scores indicate stronger recommendations
  • Test with different limits: Find the right number of recommendations for your use case
  • Use user history: Provide user interaction history for more personalized results

​
Recommendation Strategies Explained

​
Similar Strategy

  • Best for: “More like this”, “Related items”, “You might also like”
  • How it works: Finds items with similar vector embeddings to the source
  • Use case: When users want items similar to what they’re viewing

​
Diverse Strategy

  • Best for: Discovery, avoiding filter bubbles, showing variety
  • How it works: Finds items that are different from each other while still relevant
  • Use case: When you want to show users new and varied content
  • Best for: Trending items, top sellers, general recommendations
  • How it works: Finds items that are popular across all users
  • Use case: For new users or when you want to show trending content

​
Best Practices

  • Start with similar strategy: Most users expect recommendations similar to what they like
  • Use diverse for discovery: Help users find new content they might not have discovered
  • Combine with user history: More interaction data leads to better personalization
  • Exclude irrelevant items: Use exclude_ids to avoid recommending inappropriate items
  • Monitor performance: Track which recommendations users actually engage with
  • A/B test strategies: Experiment with different approaches to see what works best