Auctions are the mechanism through which a piece of real estate on your website is sold to the highest bidder, this is, the vendor who set the highest bid among those who had an interest in a given page/view location on your web or mobile app.

Topsort provides auctions as a service, which means your app can use Topsort to run auctions and harness state-of-the-art technology without having to worry about the intricacies of auction theory.

Typical response times are around 10ms. Since these requests must precede products/banners rendering in your app, we are constantly working towards maintaining and reducing response times in order to minimize Topsort's footprint on your app's performance.

📘

Prerequisites

Go to API Reference / Create a new auction

Running Auctions

To run an auction, there are several pieces of information that the marketplace app should provide. These are the product IDs that will participate in the auction, the type of auction (banner or listings), and the number of slots available for promoted content on the page that will be rendered.

You must also include the authorization header as explained here.

We do not recommend running an auction when the user sets up filtering options (e.g. brand) or if they manually sort results.

Request Fields

Product IDs

The most important piece of information you must provide is the IDs of the products that will participate in the auction. Usually, these are the products that appear in whichever listing you will display on your page, e.g. if your app is related to bicycles and you are rendering the "Bike helmets" category page, you must provide the product IDs for all bike helmets, even if they wouldn't normally appear immediately due to pagination.

Type

With Topsort, you can run auctions for sponsored listings or banners. While running auctions, the type of the auction (listings or banner) needs to be specified.

Slots

The slots object is used by our engine to define how many slots should it run the auctions for.

Auction Results

For each entry in the results object, the endpoint will return the results of the auction items (up to 5) in an array that contains auction winners.

Each of these array items contains the rank and Resolved Bid ID of the products that won the auction. Non-winners (or their ranks) are not returned.

Remember that only products which have an active bid in Topsort may win an auction. Also, keep in mind that the number of slots is only an upper bound for the number of auction winners but the actual number may be less than that. For instance, there might be no active bids for the products on a page at a given time, and therefore there will be no winners when running an auction for those products. The app implementation must take this case into consideration.

❗️

Avoid caching results

  • Auction results must not be reused across different users; Topsort's data analytics relies on distinct session data.
  • Auction results should not be reused across reloads of a single page;
  • Auction results should not be cached; cached data might be outdated by the time it's used in the marketplace.
  • Of course, you may cache product IDs to be sent in /auctions requests if needed.

Examples

Below is a sample recipe for running an auction on a search page, available for Python and NodeJS.