Get Recommendations

The Recommendation API processes requests through a deterministic four-stage pipeline:

• Request Validation: Validates partnerName, locale, and currency.

• Algorithm Selection: Executes the logic associated with the {algorithm_name} path parameter.

• Smart Routing: For analytics-driven algorithms, the engine dynamically adjusts the variant (e.g., applying category-specific logic if categoryList is present).

• Fallback Logic: If the primary algorithm returns zero or insufficient results, a pre-configured fallback algorithm populates the remaining slots.

• Output Generation: Returns a JSON payload containing product identifiers or full metadata objects.

Endpoint

The Recommendation API follows a standard RESTful pattern:

GET https://recommendation.api.useinsider.com/v2/{algorithm-name}

Examples:

• /v2/most-popular - Most viewed products

• /v2/user-based - Personalized user recommendations

• /v2/purchased-together - Frequently bought together items

Before making your first request, you'll need:

• API Token - Used to authenticate your requests to the Smart Recommender API.

  All requests require your API token in the request header.

• Partner ID/Name - Your store identifier

• Locale - Language and region code used for recommendation context (e.g., en_US, fr_FR)

• Currency - Currency code (e.g., USD, EUR)

Algorithm Abbreviations

Each algorithm has a short abbreviation used in response payloads:

• mvop = Most Popular Items

• ub = User Based

• btb = Purchased Together

• chef = Chef (automated strategy selector)

Refer to the Algorithm Descriptions for the complete list.

Query Parameters

All endpoints support common parameters:

Sample Request

curl -X GET "https://recommendation.api.useinsider.com/v2/most-popular?partnerName=dataforceapi&locale=tr_TR&size=1&details=true" \
                    -H "Authorization: Bearer YOUR_API_TOKEN"

const apiToken = 'YOUR_API_TOKEN';
                    const endpoint = 'https://recommendation.api.useinsider.com/v2/most-popular';

                    const params = {
                    partnerName: 'dataforceapi',
                    locale: 'tr_TR',
                    size: 1,
                    details: true
                    };

                    const queryString = new URLSearchParams(params).toString();

                    fetch(`${endpoint}?${queryString}`, {
                    method: 'GET',
                    headers: {
                    'Authorization': `Bearer ${apiToken}`
                    }
                    })
                    .then(response => response.json())
                    .then(data => console.log(data))
                    .catch(error => console.error('Error:', error));

import requests

                    api_token = 'YOUR_API_TOKEN'
                    endpoint = 'https://recommendation.api.useinsider.com/v2/most-popular'

                    params = {
                    'partnerName': 'dataforceapi',
                    'locale': 'tr_TR',
                    'size': 1,
                    'details': True
                    }

                    headers = {
                    'Authorization': f'Bearer {api_token}'
                    }

                    response = requests.get(endpoint, params=params, headers=headers)
                    data = response.json()
                    print(data)

Sample Response

Responses follow a consistent JSON structure:

{
        "success": true,
        "total": 10,
        "types": {
        "mvop": 10
        },
        "data": ["productId1", "productId2", ...]
        }

With details=true, the data array contains full product objects including pricing, images, categories, and attributes.

200 / Success-OK

A successful response looks like this:

{
    "success": true,
    "total": 1,
    "types": {
        "mvop": 1
    },
    "data": ["SKU-DK-0011"]
}

Getting Product Details

By default, the API returns only product IDs. To get full product information (images, prices, descriptions), add details=true.

curl -X GET "https://recommendation.api.useinsider.com/v2/most-popular?partnerName=dataforceapi&locale=tr_TR&size=1&details=true" \ 
 -H "Authorization: Bearer YOUR_API_TOKEN"

const params = { 
 partnerName: 'dataforceapi', 
 locale: 'tr_TR', 
 size: 1, 
 details: true 
};

params = { 
 'partnerName': 'dataforceapi', 
 'locale': 'tr_TR', 
 'size': 1, 
 'details': True 
}

Response with details=true includes:

• image_url - Product image

• name - Product name

• price - Product pricing (by currency)

• category - Product categories

• discount - Discount information

• in_stock - Stock status

Here is a full example with details=true:

{
    "success": true,
    "total": 1,
    "types": {
        "mvop": 1
    },
    "data": [
        {
            "item_id": "SKU-HA-0011",
            "name": "Hummingbird Decorative Cushion",
            "locale": "en_US",
            "image_url": "https://cdn.demo-shop.com/images/home-accessories/hummingbird-cushion-45x45.jpg",
            "url": "https://www.demo-shop.com/en/home-accessories/hummingbird-decorative-cushion?ins_sr=eyJwcm9kdWN0SWQiOiJTS1UtSEEtMDAxMSJ9",
            "in_stock": 1,
            "price": {
                "USD": 24.99
            },
            "original_price": {
                "USD": 29.99
            },
            "discount": {
                "USD": 5.0
            },
            "category": [
                "Home Accessories",
                "Decorative Cushions"
            ],
            "description": "Soft cotton decorative cushion with hummingbird pattern. Ideal for living rooms and bedrooms.",
            "brand": "Demo Home",
            "color": "Multicolor",
            "size": "45x45 cm",
            "tags": [
                "cushion",
                "home-decor",
                "living-room"
            ],
            "material_type": "Cotton",
            "washable": "Yes",
            "room": "Living Room"
        }
    ]
}

API Rate Limits

The rate limit for direct API calls is set to 1000 calls per minute, applied across all endpoints of the Recommendation API. Exceeding this rate limit causes additional requests to return 429 status codes.

If your technical architecture requires a higher throughput, contact the Insider One team.