Navigation
API v1 API v2

Recommender API V1

Use the Recommender API to retrieve personalized product suggestions, alternatives, and bestsellers.

Overview

Note This endpoint is publicly available and requires no authentication.

The Recommender API allows you to retrieve personalized product suggestions, alternatives, and bestsellers programmatically. It is designed to personalize the user experience by delivering relevant content based on user interaction history, item popularity, and similarity.

Features include:

  • Flexibility: Request different types of recommendations (e.g., alternatives, cross-sells, last viewed) in a single batch.
  • Context Awareness: Filter recommendations dynamically based on the user's current context (e.g., gender, category).
  • Business Logic: Apply availability checks or warehouse-specific logic.

Important To use this feature, you must synchronize your product data and integrate analytics to enable personalization.

POST https://live.luigisbox.tech/v1/recommend

Request Parameters

To get recommendations, send a POST request to the endpoint. The tracker_id is passed as a query parameter, while the specific recommendation details are sent in the JSON body.

Query Parameters

Parameter Type Required Description
tracker_id string ✓ Your unique site identifier within Luigi's Box.

Request Body

The request body is a JSON array of recommendation request objects. This allows you to request multiple different recommendations (batching) in a single HTTP call.

Parameter Type Description
recommendation_type string Required. Identifier of the recommender model (e.g., bestsellers, item_detail_alternatives). See Recommender models.
recommender_client_identifier string Arbitrary ID to tag specific widget locations (e.g., 'homepage_hero', 'cart_cross_sell'). Useful for analytics segmentation.
user_id string Unique user identifier. Send the value of the _lb cookie to enable personalization based on browsing history.
item_ids array List of item IDs to base recommendations on. Required for contextual models like 'alternatives' or 'related'. Note: Only the first 10 entries are used.
size integer Number of items to return. Default is 10. Maximum is 50.
hit_fields array List of specific fields to retrieve (e.g., ['title', 'url', 'price']).
blacklisted_item_ids array List of item IDs to explicitly exclude from results.
recommendation_context object Defines request-time restrictions (filters).
Format: 'field': {'values': [...], 'operator': '...'}

Examples:
• OR logic: {'gender': {'values': ['woman', 'unisex'], 'operator': 'or'}}
• AND logic: {'tags': {'values': ['sale', 'new'], 'operator': 'and'}}
• NOT logic: {'allergens': {'values': ['nuts'], 'operator': 'not'}}
• Ranges: Use | pipe (e.g., 'price': {'values': ['10|50']}).

Combined (Multiple Filters):
{ 'gender': {'values': ['woman'], 'operator': 'or'}, 'brand': {'values': ['Nike'], 'operator': 'not'} }
settings_override object Overrides default settings. Common use case: Multi-warehouse availability.
Example: {'availability_field': 'warehouse_2_availability'}.
mark_fallback_results boolean If true, the response will indicate if a result came from the primary strategy or a fallback.

Request Headers

Header Value
Content-Type application/json; charset=utf-8
Accept-Encoding gzip, deflate (Recommended)

Example Request


curl -X POST "https://live.luigisbox.tech/v1/recommend?tracker_id=YOUR_TRACKER_ID" \
     -H "Content-Type: application/json" \
     -H "Accept-Encoding: gzip, deflate" \
     -d '[
           {
             "recommendation_type": "item_detail_alternatives",
             "item_ids": ["/products/123"],
             "size": 4
           }
         ]'

How to make a request

The following examples demonstrate how to send a request to the Recommender API using various languages.

To make a valid recommendation request:

  • Endpoint: POST to https://live.luigisbox.tech/v1/recommend.
  • Authentication: Provide your tracker_id in the URL.
  • Payload: Construct a JSON array containing one or more recommendation objects.
  • Headers: Set Content-Type: application/json and Accept-Encoding: gzip.

Tip If you need recommendations for multiple widgets (e.g., "Similar Products" and "Top Sellers") on the same page, include both objects in the array to fetch them in a single network request.

Example Code

# --- Ruby Example for POST /v1/recommend ---
# Assumes 'faraday' gem is installed


require 'faraday'
require 'json'



LUIGISBOX_HOST = 'https://live.luigisbox.tech'
ENDPOINT_PATH = '/v1/recommend'
TRACKER_ID = 'your_tracker_id'



connection = Faraday.new(url: LUIGISBOX_HOST) do |conn|
  conn.use FaradayMiddleware::Gzip
end



# Define the recommendation request body
payload = [
  {
    "recommendation_type" => "item_detail_alternatives",
    "recommender_client_identifier" => "item_detail",
    "item_ids" => ["/products/123"],
    "size" => 4,
    "user_id" => "user_session_id"
  }
]



response = connection.post(ENDPOINT_PATH) do |req|
  req.params['tracker_id'] = TRACKER_ID
  req.headers['Content-Type'] = 'application/json'
  req.headers['Accept-Encoding'] = 'gzip, deflate'
  req.body = payload.to_json
end



if response.success?
  puts "Recommendations: #{JSON.pretty_generate(JSON.parse(response.body))}"
else
  puts "Error: #{response.status} - #{response.body}"
end

<?php
// PHP Example for POST /v1/recommend
// Assumes Guzzle is installed


require 'vendor/autoload.php';
use GuzzleHttp\Client;



$LUIGISBOX_HOST = 'https://live.luigisbox.tech';
$ENDPOINT_PATH = '/v1/recommend';
$TRACKER_ID = 'your_tracker_id';



$client = new GuzzleHttp\Client();



$payload = [
    [
        "recommendation_type" => "item_detail_alternatives",
        "recommender_client_identifier" => "item_detail",
        "item_ids" => ["/products/123"],
        "size" => 4,
        "user_id" => "user_session_id"
    ]
];



$response = $client->request('POST', "{$LUIGISBOX_HOST}{$ENDPOINT_PATH}", [
    'query' => ['tracker_id' => $TRACKER_ID],
    'json' => $payload,
    'headers' => ['Accept-Encoding' => 'gzip, deflate']
]);



if($response->getStatusCode() == 200) {
    echo json_encode(json_decode($response->getBody()), JSON_PRETTY_PRINT);
} else {
    echo "Error: " . $response->getStatusCode();
}

const axios = require('axios');


// V1 Recommender Request
const LUIGISBOX_HOST = 'https://live.luigisbox.tech';
const ENDPOINT_PATH = '/v1/recommend';
const TRACKER_ID = 'your_tracker_id';



const payload = [
  {
    recommendation_type: "item_detail_alternatives",
    recommender_client_identifier: "item_detail",
    item_ids: ["/products/123"],
    size: 4,
    user_id: "user_session_id"
  }
];



axios.post(LUIGISBOX_HOST + ENDPOINT_PATH, payload, {
  params: { tracker_id: TRACKER_ID },
  headers: {
    'Content-Type': 'application/json',
    'Accept-Encoding': 'gzip, deflate'
  }
})
.then(response => {
  console.log("Recommendations:", JSON.stringify(response.data, null, 2));
})
.catch(error => {
  console.error("Error:", error.message);
});

Response Structure

The response is a JSON array corresponding to the order of the request objects.

Response Attributes

Field Type Description
recommendation_id string Unique ID for the generated recommendation batch.
recommendation_type string The type of model used (echoed from request).
hits array The list of recommended items.
hits[].type string Usually item.
hits[].url string The identity of the product.
hits[].attributes object Contains the product data (title, price, image, etc.).
generated_at string Timestamp of generation.

Example Response

[
  {
    "generated_at": "2025-01-13T12:00:00+00:00",
    "recommendation_id": "req-123-abc",
    "recommendation_type": "item_detail_alternatives",
    "recommender_client_identifier": "item_detail",
    "hits": [
      {
        "url": "/products/123456",
        "type": "item",
        "attributes": {
          "title": "Premium Wireless Headphones",
          "price": "199.00 EUR",
          "image_link": "http://myshop.com/imgs/headphones.jpg",
          "availability": "in_stock"
        }
      },
      {
        "url": "/products/789012",
        "type": "item",
        "attributes": {
          "title": "Standard Wired Headphones",
          "price": "89.00 EUR",
          "image_link": "http://myshop.com/imgs/wired.jpg",
          "availability": "in_stock"
        }
      }
    ]
  }
]

Error Handling

The API uses standard HTTP status codes to indicate success or failure.

HTTP Status

Status Description
200 OK Success. The body contains the recommendation results.
400 Bad Request Malformed JSON or missing required parameters (e.g., tracker_id).
500 Server Error Internal error. If persistent, contact support.

Example Error

{
  "type": "error",
  "message": "Tracker ID is missing"
}