Get Recommendations

The Recommendation API (SR-API) is a RESTful service for programmatically retrieving personalized product suggestions. It serves as the interface to Insider One’s recommendation engine, utilizing machine learning models, real-time user behavior analysis, and product affinity data to return structured item sets.

Endpoint

The Recommendation API follows a standard RESTful pattern:

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

{algorithm-name} is the unique identifier for the recommendation logic to be executed.

Examples:

• /v2/most-popular - Most viewed products

• /v2/user-based - Personalized user recommendations

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

Refer to Algorithm Descriptions for the full list.

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.

  X-Auth-Token: YOUR_API_TOKEN

• 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=yourpartnername&locale=tr_TR&size=1&details=true" \
                    -H "X-Auth-Token: YOUR_API_TOKEN"

const apiToken = 'YOUR_API_TOKEN';
                    const endpoint = 'https://recommendation.api.useinsider.com/v2/most-popular';
                    const params = {
                    partnerName: 'yourPartnerName',
                    locale: 'tr_TR',
                    size: 1,
                    details: true
                    };
                    const queryString = new URLSearchParams(params).toString();
                    fetch(`${endpoint}?${queryString}`, {
                    method: 'GET',
                    headers: {
                    'X-Auth-Token': apiToken
                    }
                    })
                    .then(response => response.json())

import requests

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

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

                    headers = {
                    'X-Auth-Token': 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=yourpartnername&locale=tr_TR&size=1&details=true" \
                    -H "X-Auth-Token: YOUR_API_TOKEN"

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

params = {
                    'partnerName': 'yourpartnername',
                    '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.