Sponsored Banners on category pages

Working with product categories in the Topsort ecosystem

Banner Ads on Category Pages

To display banner ads on category pages, the process is similar to that of search result pages. Instead of using the searchQuery field, you should use the category field in your auction request.

There are three options for specifying the category of brands, products, or vendors participating in the auction:

• Single Category
• Multiple Categories
• Category Disjunctions

Request Example - Single Category Banner

Receive up to 5 auction results in 1 API call

{
  "auctions": [
    {
      "type": "banners",
      "slots": 1,
      "slotId": "homepage",
      "device": "mobile",
      "category": {
        "id": "c_yogurt"
      }
    }
  ]
}

Response Example - Category

{
  "results": [
    {
      "winners": [
        {
          "rank": 1,
          "winnerType": "product",
          "winnerId": "p_PJbnN",
          "resolvedBidId": "WyJlX1BKYm5OIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwiYmFubmVyQWRzIiwiZGVmYXVsdCIsIiJd",
          "asset": [
            {
              "url": "https://topsort.cdnprovider.com/lhs-banner-image-for-p_PJbnN-1x.png"
            }
          ]
        }
      ],
      "error": false
    }
  ]
}

Example: Category Disjunctions

Category disjunctions allow you to target multiple categories in a single auction request. You can specify multiple categories and the auction will consider ads from any of those categories. This is useful when you want to display banner ads that are relevant to various categories on a specific page.

Here’s an auction request with a single banner slot targeting both hiking boots and running shoes categories using category disjunctions:

{
  "auctions": [
    {
      "type": "banners",
      "slots": 1,
      "slotId": "categories-ribbon",
      "category": {
        "disjunction": [
          {
            "id": "hiking_boots"
          },
          {
            "id": "running_shoes"
          }
        ]
      } 
    }
  ]
}

The sample response below includes all the necessary information to serve the banner ads:

{
  "results": [
    {
      "winners": [
        {
          "rank": 1,
          "winnerType": "vendor",
          "winnerId": "p_PJbnN",
          "resolvedBidId": "WyJlX1BKYm5OIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwiYmFubmVyQWRzIiwiZGVmYXVsdCIsIiJd",
          "asset": [
            {
              "url": "https://topsort.cdnprovider.com/lhs-banner-image-for-p_PJbnN-1x.png"
            }
          ]
        }
      ],
      "error": false
    }
  ]
}

You can request up to 5 auctions in a single request. If you have multiple banner slots on your category pages, you can request auctions for them in one call.