Top Items API

Overview

The Top Items API returns the most popular or most relevant objects from the index, even when the user has not entered a search query. It is commonly used for “popular items” or “recommended for you” widgets.

Request parameters

To request global top items, provide your tracker ID and the object types you want returned.

Required parameters

Parameter	Type	Required	Description
`tracker_id`	string	✓	Your unique site identifier within Luigi’s Box.
`type`	string	✓	Result types and counts in the format `type:count`, for example `item:6,category:3`.

Optional parameters

Parameter	Type	Description
`f_type[]`	string	Filters results for a specific type in the format `f_<type>[]=<field>:<value>`. Supports exact matches, repeated OR filters, and ranges such as `price:10\|50`.
`hit_fields`	string	Comma-separated list of fields to return, for example `title,url,price`.
`ctx[]`	string	Model-selection context in `key:value` format, for example `ctx[]=warehouse:berlin`. Keys must match contexts reported in Analytics.

Request headers

Header	Value	Required	Description
`Accept-Encoding`	`gzip, deflate`	Recommended	Enables compressed responses to reduce payload size.

How to Make a Request

To make a valid request:

Send a GET request to https://live.luigisbox.com/v1/top_items.
Provide tracker_id and the requested type counts.
Add filters or model context only when needed for the placement.

For implementation guidance, see Quickstart: Top Items API.

Code Examples

require 'faraday'
require 'json'

connection = Faraday.new(url: 'https://live.luigisbox.com')
response = connection.get('/v1/top_items') do |req|
  req.params['tracker_id'] = 'your_tracker_id'
  req.params['type'] = 'item:10'
  req.headers['Accept-Encoding'] = 'gzip, deflate'
end

puts response.body if response.success?

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();
$response = $client->request('GET', 'https://live.luigisbox.com/v1/top_items', [
    'query' => [
        'tracker_id' => 'your_tracker_id',
        'type' => 'item:10',
    ],
    'headers' => [
        'Accept-Encoding' => 'gzip, deflate',
    ],
]);

echo $response->getBody();

const axios = require('axios');

axios
  .get('https://live.luigisbox.com/v1/top_items', {
    params: {
      tracker_id: 'your_tracker_id',
      type: 'item:10',
    },
    headers: {
      'Accept-Encoding': 'gzip, deflate',
    },
  })
  .then((response) => console.log(response.data))
  .catch((error) => console.error(error));

Response structure

The response is a JSON object containing the resulting items.

Response attributes

Field	Type	Description
`hits`	array	The list of returned objects.
`hits[].type`	string	Object type, for example `item` or `category`.
`hits[].url`	string	Unique identity of the result object.
`hits[].attributes`	object	Indexed fields such as title, price, or image links.
`hits[].pinned`	boolean	Present when the result was added by customization.
`hits[].exact`	boolean	Indicates whether the result is an exact match.

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

Use this endpoint to retrieve recommendations based on a specific user’s history.

For standard item recommendations, request type=item:10.
If you request type=queries, the endpoint returns the last queries performed by that user.

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	✓	Requested object types and counts.

Optional parameters

Parameter	Type	Description
`ctx[]`	string	Model-selection context parameters.

How to Make a Personalized Request

Include the user_id parameter whenever you want Luigi’s Box to rank results for a specific user profile.

Code Examples

require 'faraday'
require 'json'

connection = Faraday.new(url: 'https://live.luigisbox.com')
response = connection.get('/v1/personalized_top_items') do |req|
  req.params['tracker_id'] = 'your_tracker_id'
  req.params['user_id'] = 'UID'
  req.params['type'] = 'item:10'
  req.headers['Accept-Encoding'] = 'gzip, deflate'
end

puts response.body if response.success?

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();
$response = $client->request('GET', 'https://live.luigisbox.com/v1/personalized_top_items', [
    'query' => [
        'tracker_id' => 'your_tracker_id',
        'user_id' => 'UID',
        'type' => 'item:10',
    ],
    'headers' => [
        'Accept-Encoding' => 'gzip, deflate',
    ],
]);

echo $response->getBody();

const axios = require('axios');

axios
  .get('https://live.luigisbox.com/v1/personalized_top_items', {
    params: {
      tracker_id: 'your_tracker_id',
      user_id: 'UID',
      type: 'item:10',
    },
    headers: {
      'Accept-Encoding': 'gzip, deflate',
    },
  })
  .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 succeeded and results are returned.
`400 Bad Request`	The request was malformed — missing or invalid parameters.
`404 Not Found`	The `tracker_id` does not match any known catalog.
`500 Server Error`	Internal error. If persistent, contact support.
`504 Gateway Timeout`	The request took too long to process. Retrying may succeed.

{
  "tracker_id": ["tracker_id must be filled"]
}

Catalog for tracker_id: "your-tracker-id" not found.