Navigation
API v1 API v2

Top Items API

Retrieve most popular items of any type using the Top Items API.

Overview

The Top Items API allows you to retrieve the most popular or relevant items (or any other object type) from the index, even without a specific search query. This is often used to populate "Recommended for you" or "Popular items" widgets on the homepage.

GET https://live.luigisbox.tech/v2/top_items

Request Parameters

Required parameters

Info
Note on Caching: This endpoint is cached internally. Updates to product data may take a few minutes to appear.

Parameter Type Required Description
tracker_id string ✓ Your unique site identifier within Luigi's Box.
type string ✓ Specifies the type of objects to retrieve and the quantity. Example: item:10 to get top 10 items.

Optional parameters

Parameter Type Description
Identity & Personalization
auth_user_id string Logged-in User ID.
Unique identifier for personalization. Must match the customer_id in Analytics.
device_user_id string Anonymous Device ID.
Set this to the analytics client_id (cookie) when using auth_user_id to track sessions across logins.
personalize boolean Set to true to enable personalized re-ranking. Requires auth_user_id.
Filtering & Context
f_type[] string Filters results. Format: f_<type>[]=<field>:<value>.
Supports multiple values (OR logic) and ranges (|).
hit_fields string Comma-separated list of fields to retrieve (e.g., title,url,price).
ctx[] string Context parameters for dynamic model selection (e.g., warehouse:berlin).

Request Headers

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.

Example Request


curl "https://live.luigisbox.tech/v2/top_items?tracker_id=YOUR_TRACKER_ID&type=item:10" \
     -H "Accept-Encoding: gzip, deflate"

How to make a request

The following examples demonstrate how to send a request to the Top Items API.

To make a valid request:

  1. Endpoint: Use https://live.luigisbox.tech/v2/top_items.
  2. Parameters: Provide your tracker_id and the type of items to retrieve (e.g., item:10).
  3. Personalization: (Optional) Include user_id and set personalize=true to get results tailored to the user.

For a complete guide on implementation strategies, see Quickstart: Implementing Top Items Suggestions.

Example Code

# --- Ruby Example for GET /v2/top_items ---
# Assumes 'faraday' gem is installed (gem install faraday)


require 'faraday'
require 'json'



LUIGISBOX_HOST = 'https://live.luigisbox.tech'
ENDPOINT_PATH = '/v2/top_items'
TRACKER_ID = 'your_tracker_id'



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



response = connection.get(ENDPOINT_PATH) do |req|
  req.params['tracker_id'] = TRACKER_ID
  req.params['type'] = 'item:10'
  req.headers['Accept-Encoding'] = 'gzip, deflate'
end



if response.success?
  puts "Top Items: " +
       "#{JSON.pretty_generate(JSON.parse(response.body))}"
else
  puts "Error: HTTP Status " +
       "#{response.status}, Response: #{response.body}"
end

<?php
// PHP Example for GET /v2/top_items
// Assumes Guzzle is installed: 
// composer require guzzlehttp/guzzle


require 'vendor/autoload.php';



use GuzzleHttp\Client;



$LUIGISBOX_HOST = 'https://live.luigisbox.tech';
$ENDPOINT_PATH = '/v2/top_items';
$TRACKER_ID = 'your_tracker_id';



$client = new GuzzleHttp\Client();
$response = $client->request(
    'GET', 
    "{$LUIGISBOX_HOST}{$ENDPOINT_PATH}", 
    [
        'query' => [
            'tracker_id' => $TRACKER_ID,
            'type' => 'item:10'
        ],
        'headers' => [
            'Accept-Encoding' => 'gzip, deflate'
        ]
    ]
);



if($response->getStatusCode() == 200) {
    echo "Top Items:" . PHP_EOL;
    echo json_encode(json_decode($response->getBody()), JSON_PRETTY_PRINT);
} else {
    echo "Error: HTTP Status " . 
         $response->getStatusCode() . 
         "\nResponse: " . $response->getBody();
}

const axios = require('axios');


// V2 Top Items Request
const LUIGISBOX_HOST = 'https://live.luigisbox.tech';
const ENDPOINT_PATH = '/v2/top_items';
const TRACKER_ID = 'your_tracker_id';



axios.get(LUIGISBOX_HOST + ENDPOINT_PATH, {
  params: {
    tracker_id: TRACKER_ID,
    type: 'item:10'
  },
  headers: {
    'Accept-Encoding': 'gzip, deflate'
  }
})
.then(response => {
  console.log("Top Items:", 
              JSON.stringify(response.data, null, 2));
})
.catch(error => {
  if (error.response) {
    console.error("Error: HTTP Status " + error.response.status + 
                  ", Response: " + JSON.stringify(error.response.data));
  } else {
    console.error("Exception:", error.message);
  }
});

Response Structure

The response contains the list of top hits.

Response Attributes

Field Type Description
hits array The list of top items.
hits[].type string The object type (e.g. item).
hits[].identity string The unique identifier or URL of the object.
hits[].exact boolean Typically true for top items.
hits[].attributes object The indexed content of the object.

Example Response

{
    "hits": [
        {
            "identity": "http://www.e-shop.com/products/123456",
            "type": "item",
            "exact": true,
            "attributes": {
                "title": "Product X",
                "price": "5.52 EUR"
            }
        }
    ]
}

Error Handling

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

HTTP Status Description
200 OK The request was successful and results are returned.
400 Bad Request The request was malformed (e.g., missing tracker_id).
504 Gateway Timeout The request took too long to process. Retrying might succeed.

Example Error

{
  "type": "malformed_input",
  "reason": "incorrect parameters provided"
}