Banner Campaigns

Banner campaigns let you promote products, categories, brands, or seasonal content directly inside Luigi's Box autocomplete and search results. In the Luigi's Box application, you define which queries should trigger a banner, what image should be shown, where it should appear, and where the user should land after clicking it. When a query matches that configuration, Luigi's Box adds the relevant banner data to the autocomplete or search response.

There is no separate banners endpoint. Banner campaign data is included in the standard autocomplete and search responses under the campaigns key.

Choose your integration path

Using autocomplete.js or search.js

If you are using Luigi's Box frontend libraries, banner campaign support is already built in. Once you configure banner campaigns in the Luigi's Box application, the libraries will render them automatically in their supported positions.

In practice, this means you usually do not need to change your API requests or write any rendering code.

Using the API directly

If you built your own autocomplete or search UI on top of Luigi's Box APIs, you must render banners yourself.

You do not need any special request parameters. When a query matches an active banner campaign, the response includes a campaigns array. Your integration is responsible for:

• reading the returned positions
• choosing the appropriate image URL for desktop or mobile
• rendering the banner into your UI
• linking the banner to the destination URL returned by the campaign

If you want a step-by-step implementation guide, start with one of these quickstarts:

• Quickstart: Rendering banner campaigns with the Autocomplete API
• Quickstart: Rendering banner campaigns with the Search API

Response structure

The campaigns array contains one or more campaign objects. Each object describes a banner campaign that matched the current query.

Each campaign object contains:

• id - campaign identifier
• target_url - destination URL opened after click
• banners - object keyed by banner position

The banners object contains one or more fixed position names, such as autocomplete_top or search_header. Each position contains the image URLs for that placement.

Each position inside banners contains:

• desktop_url - image for larger screens
• mobile_url - image for smaller screens

Every banner campaign is tied to at least one query in the Luigi's Box application. The campaign is returned only when the current query matches that configuration.

In other words, the response is layered like this:

• campaigns tells you which campaigns matched
• target_url tells you where the click should go
• banners tells you which positions are available
• desktop_url and mobile_url tell you which image asset to render there

Autocomplete response example

If you define banners for autocomplete positions, the response can look like this:

{
  ...
  "campaigns": [
    {
      "id": 9,
      "target_url": "https://www.e-shop.com/harry-potter",
      "banners": {
        "autocomplete_list": {
          "desktop_url": "https://www.e-shop.com/harry-potter-1.jpg",
          "mobile_url": "https://www.e-shop.com/harry-potter-2.jpg"
        }
      }
    },
    {
      "id": 12,
      "target_url": "https://www.e-shop.com/rowling",
      "banners": {
        "autocomplete_top": {
          "desktop_url": "https://www.e-shop.com/rowling-1.jpg",
          "mobile_url": "https://www.e-shop.com/rowling-2.jpg"
        }
      }
    }
  ]
  ...
}

In this example, the response contains two campaigns. One campaign provides an autocomplete_list banner and the other provides an autocomplete_top banner.

Search response example

If you define banners for search result positions, the response can look like this:

{
  ...
  "campaigns": [
    {
      "id": 13,
      "target_url": "https://www.e-shop.com/harry-potter",
      "banners": {
        "search_header": {
          "desktop_url": "https://www.e-shop.com/harry-potter-1.jpg",
          "mobile_url": "https://www.e-shop.com/harry-potter-2.jpg"
        },
        "search_footer": {
          "desktop_url": "https://www.e-shop.com/harry-potter-3.jpg",
          "mobile_url": "https://www.e-shop.com/harry-potter-4.jpg"
        }
      }
    }
  ]
  ...
}

The same campaign can provide banners for more than one position.

In this example, a single campaign provides both search_header and search_footer, which means the same query can show banners in multiple places on the page.

Banner Positions

Luigi's Box uses fixed position names in both the application and the API response:

If you use Luigi's Box frontend libraries, the dimensions below reflect the expected default placements.

If you use a custom backend or frontend integration, you can render banners in your own layout and at your own dimensions. Only the position keys themselves are fixed.

autocomplete_list

Banner displayed in the autocomplete list area.

Banner within list of brands in autocomplete

Computer devices
310x240px (JPG, 620x480, max 600kb)

Mobile devices
420x240px (JPG, 840x480, max 600kb)

autocomplete_top

Banner displayed around the featured top-product area in autocomplete.

Banner within top product in autocomplete

Computer devices
240x450px (JPG, 480x900, max 600kb)

Mobile devices
420x240px (JPG, 840x480, max 600kb)

search_header

Banner displayed above the search results.

Banner within header in search results

Computer devices
1024x160px (JPG, 2048x320, max 600kb)

Mobile devices
420x240px (JPG, 840x480, max 600kb)

search_panel

Banner displayed in the side panel of the search page.

Banner within side panel in search results

Computer devices
240x280px (JPG, 480x460, max 600kb)

Mobile devices
420x240px (JPG, 840x480, max 600kb)

search_list

Banner displayed directly inside the list of search results.

Banner within product in the list in search results

Computer devices
340x490px (JPG, 680x980, max 600kb)

Mobile devices
340x490px (JPG, 680x980, max 600kb)

search_footer

Banner displayed below the search results.

Banner within footer in search results

Computer devices
1024x160px (JPG, 2048x320, max 600kb)

Mobile devices
420x240px (JPG, 840x480, max 600kb)