---
title: Banner campaigns
description: Display promotional banners in autocomplete and search results for specific queries.
slug: search/guides/banner-campaigns
docKind: guide
hub: search
---

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.

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

:::caution
If you use [autocomplete.js](/autocomplete/autocomplete-js/) or [search.js](/search/search-js/) with the default templates and only light styling changes, banner campaigns work out of the box. If you heavily customize the markup or CSS, you may need to add your own styling adjustments so the banners fit your layout correctly.
:::

:::note
Luigi's Box does not host the banner images for you. Each banner references image URLs that you host on your side. Your frontend should render those images and link them to the campaign destination URL returned in the API response.
:::

## 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 render them automatically.

### 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. 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

## 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

Each position inside `banners` contains:

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

## Autocomplete response example

```json
{
  "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"
        }
      }
    }
  ]
}
```

## Search response example

```json
{
  "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"
        }
      }
    }
  ]
}
```

## Banner positions

| Area | Position key | Typical placement |
| :--- | :--- | :--- |
| Autocomplete | `autocomplete_list` | Banner inside the list area |
| Autocomplete | `autocomplete_top` | Banner next to the featured top product |
| Search | `search_header` | Banner above the result list |
| Search | `search_panel` | Banner in the side panel |
| Search | `search_list` | Banner inserted into the results list |
| Search | `search_footer` | Banner below the result list |

### `autocomplete_list`

**Desktop:** 310x240px (JPG, 620x480, max 600kb)
![Desktop banner for autocomplete_list](/images/campaigns/brand-list.png)

**Mobile:** 420x240px (JPG, 840x480, max 600kb)
![Mobile banner for autocomplete_list](/images/campaigns/brand-list-mobile.png)

### `autocomplete_top`

**Desktop:** 240x450px (JPG, 480x900, max 600kb)
![Desktop banner for autocomplete_top](/images/campaigns/top-desktop.png)

**Mobile:** 420x240px (JPG, 840x480, max 600kb)
![Mobile banner for autocomplete_top](/images/campaigns/top-mobile.png)

### `search_header`

**Desktop:** 1024x160px (JPG, 2048x320, max 600kb)
![Desktop banner for search_header](/images/campaigns/header-desktop.png)

**Mobile:** 420x240px (JPG, 840x480, max 600kb)
![Mobile banner for search_header](/images/campaigns/header-mobile.png)

### `search_panel`

**Desktop:** 240x280px (JPG, 480x460, max 600kb)
![Desktop banner for search_panel](/images/campaigns/side-panel-desktop.png)

**Mobile:** 420x240px (JPG, 840x480, max 600kb)
![Mobile banner for search_panel](/images/campaigns/top-mobile.png)

### `search_list`

**Desktop:** 340x490px (JPG, 680x980, max 600kb)
![Desktop banner for search_list](/images/campaigns/list-desktop.png)

**Mobile:** 340x490px (JPG, 680x980, max 600kb)
![Mobile banner for search_list](/images/campaigns/list-mobile.png)

### `search_footer`

**Desktop:** 1024x160px (JPG, 2048x320, max 600kb)
![Desktop banner for search_footer](/images/campaigns/footer-desktop.png)

**Mobile:** 420x240px (JPG, 840x480, max 600kb)
![Mobile banner for search_footer](/images/campaigns/footer-mobile.png)