Recommender API

You can use Luigi's Box recommendation endpoint to get recommendations from your catalog based on popularity, similarity, users' interaction history and much more.

To use this feature, you need to synchronize your product database with Luigi's Box index. See Importing your data for more details.

To take advantage of personalized and other advanced recommendations, you need to integrate Luigi's Box Analytics service with your website by following the instructions.

We strongly recommend that you do not implement the JSON API directly, but instead use our integrated Recco.js library which allows you to build a recommendation interface with minimum programming effort.

Get recommendations

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

The recommendation endpoint is publicly available and requires no authentication.

Required parameters

Parameter	Description
tracker_id	Identifier of your site within Luigi's Box. You can see this identifier in every URL in the Luigi's Box app once you are logged-in.

Request headers

Header	Content
Content-Type	application/json; charset=utf-8

Consider sending request header of Accept-Encoding as well with values for supported encoding methods of your HTTP client, e.g. gzip or br, gzip, deflate for multiple supported methods. Encodings make the response from the JSON API considerably smaller and thus faster to transfer.

Request body

Request body is a JSON array of recommendation request objects. Each recommendation request object contains the following attributes:

Attribute	Description
`recommendation_type`required	Identifier of the recommender model. See Recommender models for more details.
`recommender_client_identifier`optional	Arbitrary identifier for analytics purposes. You may use the same models in different places and the `recommender_client_identifier` helps to identify the concrete instance of the recommender. See Placement and model reuse for more details.
`user_id`required	Unique user identifier. Send the value of `_lb` cookie from your site or supply your own value. See User identifiers for more details.
`item_ids`	A list of items to base the recommendation on. Depending on the type of recommendation and placement it might be a list of resource identifiers of products in a shopping cart, or a single resource identifier of a product the user is viewing. The recommender only uses first 10 entries, you can send more, but the rest of the list will be ignored.
`blacklisted_item_ids`optional	List of product resource identifiers that must not be recommended, e.g., different product variants that are very similar to the products in `item_ids`.
`size`optional	How many recommended items you want to return. Defaults to 10, maximum is capped to 50.
`recommendation_context`optional	Object defining request-time restrictions on results being recommended (e.g., filters used by the user). It allows you to define restrictions using OR operator `{"gender": {"values": ["woman", "unisex"], "operator": "or"}}`, AND operator `{"color": {"values": ["black", "blue"], "operator": "and"}}`, NOT operator `{"allergens": {"values": ["gluten", "soya"], "operator": "not"}}`. Use the syntax known from search, using a pipe `\|`, to define range criteria for numerical or date attributes, e.g., `{"price_amount": {"values": ["4.2\|"]}}`. Multiple restrictions can be used within recommendation_context `{"gender": {"values": ["woman", "unisex"], "operator": "or"}, "price_amount": {"values": ["\|150"]}}`. Single value restrictions can be submitted also in a simplified format `{"size": "M", "category": "Summer shoes"}`.
`settings_override`optional	Object defining request-time overrides of the recommender settings. The most common use case is to define custom availability field for a multi-warehouse catalog, e.g., when a user selects his location, then a particular warehouse is selected and thus an appropriate availability field should be used: `{"availability_field": "warehouse_2_availability"}`.
`hit_fields`optional	Comma separated list of fields. Only these fields (in addition to record identifier and type) will be retrieved and present in results. If not provided, all fields will be present in results.
`mark_fallback_results`optional	Boolean allowing to mark whether the response hits were recommended by a primary strategy of by a fallback. By default disabled.

In case of multiple recommenders used on the same page, we suggest to use Batching and join all request objects into one request body for better latency and deduplication.

Sample request

require 'faraday'
require 'faraday_middleware'
require 'json'

connection = Faraday.new(url: 'https://live.luigisbox.com') do |conn|
  conn.use FaradayMiddleware::Gzip
end

response = connection.post("/v1/recommend?tracker_id=1234-5678") do |req|
  req.headers['Content-Type'] = "application/json; charset=utf-8"
  req.body = '[
  {
    "blacklisted_item_ids": [

    ],
    "item_ids": [
      "/products/012345"
    ],
    "recommendation_type": "item_detail_alternatives",
    "recommender_client_identifier": "item_detail_alternatives",
    "size": 4,
    "user_id": "6822981852855588000",
    "hit_fields": [
      "url",
      "title"
    ]
  },
  {
    "blacklisted_item_ids": [

    ],
    "item_ids": [
      "/products/012345"
    ],
    "recommendation_type": "bestsellers",
    "recommender_client_identifier": "item_detail_bestsellers",
    "size": 4,
    "user_id": "6822981852855588000",
    "hit_fields": [
      "url",
      "title"
    ]
  }
]'
end

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

#!/bin/bash

curl -i -XPOST --compressed\
  "https://live.luigisbox.com/v1/recommend?tracker_id=1234-5678"\
   -H "Content-Type: application/json; charset=utf-8"\
   -d '[
  {
    "blacklisted_item_ids": [

    ],
    "item_ids": [
      "/products/012345"
    ],
    "recommendation_type": "item_detail_alternatives",
    "recommender_client_identifier": "item_detail_alternatives",
    "size": 4,
    "user_id": "6822981852855588000",
    "hit_fields": [
      "url",
      "title"
    ]
  },
  {
    "blacklisted_item_ids": [

    ],
    "item_ids": [
      "/products/012345"
    ],
    "recommendation_type": "bestsellers",
    "recommender_client_identifier": "item_detail_bestsellers",
    "size": 4,
    "user_id": "6822981852855588000",
    "hit_fields": [
      "url",
      "title"
    ]
  }
]'

<?php

// Using Guzzle (http://guzzle.readthedocs.io/en/latest/overview.html#installation)
require 'GuzzleHttp/autoload.php';


$client = new GuzzleHttp\Client();
$res = $client->request('POST', "https://live.luigisbox.com/v1/recommend?tracker_id=1234-5678", [
  'headers' => [
    'Accept-Encoding' => 'gzip, deflate',
    'Content-Type' => 'application/json; charset=utf-8',
    'Date' => $date,
    'Authorization' => "guzzle {$public_key}:{$signature}",
  ],
  'body' => '[
  {
    "blacklisted_item_ids": [

    ],
    "item_ids": [
      "/products/012345"
    ],
    "recommendation_type": "item_detail_alternatives",
    "recommender_client_identifier": "item_detail_alternatives",
    "size": 4,
    "user_id": "6822981852855588000",
    "hit_fields": [
      "url",
      "title"
    ]
  },
  {
    "blacklisted_item_ids": [

    ],
    "item_ids": [
      "/products/012345"
    ],
    "recommendation_type": "bestsellers",
    "recommender_client_identifier": "item_detail_bestsellers",
    "size": 4,
    "user_id": "6822981852855588000",
    "hit_fields": [
      "url",
      "title"
    ]
  }
]'
]);

echo $res->getStatusCode();
echo $res->getBody();

// This endpoint requires no authentication

// Example request body

[
  {
    "blacklisted_item_ids": [

    ],
    "item_ids": [
      "/products/012345"
    ],
    "recommendation_type": "item_detail_alternatives",
    "recommender_client_identifier": "item_detail_alternatives",
    "size": 4,
    "user_id": "6822981852855588000",
    "hit_fields": [
      "url",
      "title"
    ]
  },
  {
    "blacklisted_item_ids": [

    ],
    "item_ids": [
      "/products/012345"
    ],
    "recommendation_type": "bestsellers",
    "recommender_client_identifier": "item_detail_bestsellers",
    "size": 4,
    "user_id": "6822981852855588000",
    "hit_fields": [
      "url",
      "title"
    ]
  }
]

Sample response

The API returns a JSON structured like this. The exact content of attributes field depends on the time of the request and content of your product catalog.

json

[
  {
    "generated_at": "2020-05-05T12:44:22+00:00",
    "model_version": 1588682662,
    "recommendation_id": "a24588e9-0664-4637-91d5-165313a6eac8",
    "recommendation_type": "basket",
    "recommender_client_identifier": "basket-sidebar",
    "recommender": "c01",
    "recommender_version": "b36705710",
    "user_id": "6822981852855588000",
    "hits": [
      {
        "url": "/products/123456",
        "attributes": {
          "image_link": "http://www.e-shop.com/assets/imgs/products/123456.jpg",
          "description": "Description field from your product catalog",
          "categories": [
            "Gadgets",
            "Kids"
          ],
          "title": "Product X",
          "availability_rank_text": "true",
          "price": "5.52 EUR",
          "condition": "new"
        },
        "type": "item"
      },
      {
        "url": "/products/456789",
        "attributes": {
            "image_link": "http://www.e-shop.com/assets/imgs/products/456789.jpg",
            "description": "Description field from your product catalog",
            "categories": [
                "Gadgets",
                "Kids"
            ],
            "title": "Product Y",
            "availability_rank_text": "preorder",
            "price": "12.14 EUR",
            "condition": "new"
        },
        "type": "item",
        "exact": true
      }
    ]
  }
]