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.
https://live.luigisbox.com/v2/top_items
Request Parameters
Required parameters
| 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 |
|---|---|---|
user_id |
string | User identifier. Recommended for retrieving personalized top items. |
client_id |
string | Anonymous client identifier. |
personalize |
boolean | If set to true (and user_id is provided), the API returns personalized recommendations instead of generic global top items. |
f_type[] |
string | Limits the top items to a specific subset. Example: f_item[]=category:Shoes. |
hit_fields |
string | fields to return in the attributes object. |
ctx[] |
string | Context parameters for advanced logic. |
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.com/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:
- Endpoint: Use
https://live.luigisbox.com/v2/top_items. - Parameters: Provide your
tracker_idand thetypeof items to retrieve (e.g.,item:10). - Personalization: (Optional) Include
user_idand setpersonalize=trueto 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.com'
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.com';
$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.com';
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[].exact |
boolean | Typically true for top items. |
hits[].attributes |
object | The indexed content of the object. |
Example Response
{
"hits": [
{
"url": "http://www.e-shop.com/products/123456",
"attributes": {
"title": "Product X",
"price": "5.52 EUR"
},
"type": "item",
"exact": true
}
]
}
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"
}