Navigation
API v1 API v2

Top Items API V1

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/v1/top_items

Request Parameters (V1)

To request global top items, you simply provide your tracker ID and the desired item types.

Required parameters

Parameter Type Required Description
tracker_id string ✓ Your unique site identifier within Luigi's Box. Found in the dashboard settings.
type string ✓ Defines the types of objects to return and their counts. Format: type:count.
Example: item:6,category:3.

Optional parameters

Parameter Type Description
f_type[] string Filters results of a specific type. Format: f_<type>[]=<field>:<value>.
  • Exact Match: f_item[]=color:green
  • OR Logic: f_item[]=color:green&f_item[]=color:blue
  • Ranges: price:10|50.
hit_fields string Comma-separated list of fields to retrieve (e.g., title,url,price).
ctx[] string Model Selection. Format: key:value.
Selects a specific machine learning model (e.g., ctx[]=warehouse:berlin). Keys must match contexts reported in Analytics.

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/v1/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 V1.

To make a valid request:

  1. Endpoint: Use https://live.luigisbox.tech/v1/top_items.
  2. Parameters: Provide your tracker_id and the type of items to retrieve (e.g., item:10).

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

Example Code

# --- Ruby Example for GET /v1/top_items ---
# Assumes 'faraday' gem is installed


require 'faraday'
require 'json'



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



connection = Faraday.new(url: LUIGISBOX_HOST)
response = connection.get(ENDPOINT_PATH) do |req|
  req.params['tracker_id'] = TRACKER_ID
  req.params['type'] = 'item:10'
end



puts response.body if response.success?

<?php
// PHP Example for GET /v1/top_items
// Assumes Guzzle is installed


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



$LUIGISBOX_HOST = 'https://live.luigisbox.tech';
$ENDPOINT_PATH = '/v1/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']
]);



if($response->getStatusCode() == 200) {
    echo $response->getBody();
}

const axios = require('axios');


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



axios.get(LUIGISBOX_HOST + ENDPOINT_PATH, {
  params: { tracker_id: TRACKER_ID, type: 'item:10' }
})
.then(response => console.log(response.data))
.catch(error => console.error(error));

Response Structure

The response is a JSON object containing the list of popular items.

Response Attributes

Field Type Description
hits array The list of result objects.
hits[].type string The type of the result object (e.g., item, category).
hits[].url string The unique identity of the result object.
hits[].attributes object Key-value pairs of the indexed fields (e.g., title, price, image links). Content depends on your catalog structure.
hits[].exact boolean Indicates if the result is an exact match (usually true for top items).

Example Response

{
    "hits": [
        {
            "url": "http://www.e-shop.com/products/123456",
            "attributes": {
                "image_link": "http://www.e-shop.com/assets/imgs/products/123456.jpg",
                "title": "Product X",
                "price": "5.52 EUR",
                "availability_rank_text": "true"
            },
            "type": "item",
            "exact": true
        },
        {
            "url": "http://www.e-shop.com/products/456789",
            "attributes": {
                "image_link": "http://www.e-shop.com/assets/imgs/products/456789.jpg",
                "title": "Product Y",
                "price": "12.14 EUR"
            },
            "type": "item",
            "exact": true
        }
    ]
}

Get Personalized Top Items

Serves specific recommendations based on user history.

  • Top Items: Returns items the user is most likely to engage with.
  • Last Queries: If you request type=queries, it returns the last search queries performed by this specific user.

GET https://live.luigisbox.tech/v1/personalized_top_items

Request Parameters (Personalized)

Required parameters

Parameter Type Required Description
tracker_id string ✓ Your site identifier.
user_id string ✓ User ID to personalize for.
type string ✓ Object types and counts.

Optional parameters

Parameter Type Description
ctx[] string Context parameters.

Example Request

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

How to make a personalized request

Include the user_id parameter to get personalized results.

Example Code

# --- Ruby Example for GET /v1/personalized_top_items ---
# Assumes 'faraday' gem is installed


require 'faraday'
require 'json'



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



connection = Faraday.new(url: LUIGISBOX_HOST)
response = connection.get(ENDPOINT_PATH) do |req|
  req.params['tracker_id'] = TRACKER_ID
  req.params['user_id'] = 'UID'
  req.params['type'] = 'item:10'
end



puts response.body if response.success?

<?php
// PHP Example for GET /v1/personalized_top_items
// Assumes Guzzle is installed


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



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



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



if($response->getStatusCode() == 200) {
    echo $response->getBody();
}

const axios = require('axios');


// V1 Personalized Top Items Request
const LUIGISBOX_HOST = 'https://live.luigisbox.tech';
const ENDPOINT_PATH = '/v1/personalized_top_items';
const TRACKER_ID = 'your_tracker_id';



axios.get(LUIGISBOX_HOST + ENDPOINT_PATH, {
  params: { tracker_id: TRACKER_ID, user_id: 'UID', type: 'item:10' }
})
.then(response => console.log(response.data))
.catch(error => console.error(error));

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"
}