> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topsort.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sponsored listings in search results

> Learn how to use sponsored listings on search results

The example on this page shows how to run [auctions](/en/ad-server/auctions/auctions-api) for products originating from search results.

There are two ways to run these type of auctions:

* Using the `searchQuery` parameter, where only bids that target products with matching keywords will have a chance to win such auctions.
* Using a [set of products](/en/api-reference/examples/sponsored-listings/set-of-products) and additionaly use the `searchQuery` parameter to expand the list of bids by adding products with matching keywords to the ones in the set of products.

## Use cases

Running these kind of auctions on search pages will allow your vendors to promote products inside the search results.

## Example API call

### Request: using `searchQuery`

```json theme={null}
{
  "auctions": [
    {
      "type": "listings",
      "slots": 2,
      "searchQuery": "Running shoes"
    }
  ]
}
```

The request above will create a single listings auction:

* It will have a maximum of two winners due to the `slots` field.
* The `searchQuery` field determines what keywords bid targets must have.

Only bids that target products with the `Running shoes` keyword can take part in this auction.

### Response

```json theme={null}
{
  "results": [
    {
      "winners": [
        {
          "rank": 1,
          "type": "product",
          "id": "p_Mfk15",
          "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0="
        },
        {
          "rank": 2,
          "type": "product",
          "id": "p_PJbnN",
          "resolvedBidId": "WyJlX1BKYm5OIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0="
        }
      ],
      "error": false
    }
  ]
}
```

Notable here:

* The type of the winners is `product`, because we're running a listings auction.
* There are two winners, the maximum that is allowed by the `slots` field in the request.

### Request: combining products and `searchQuery`

```json theme={null}
{
  "auctions": [
    {
      "type": "listings",
      "slots": 2,
      "products": {
        "ids": [
          "p_ojng4",
          "p_8VKDt",
          "p_Mfk15"
        ]
      }
      "searchQuery": "Running shoes"
    }
  ]
}
```

The request above will create a single listings auction:

* It will have a maximum of two winners due to the `slots` field.
* The `searchQuery` field determines what keywords bid targets must have.

Products entering this auctions will be `"p_ojng4"`, `"p_8VKDt"`, `"p_Mfk15"` and those with a keyword matching the `searchQuery`.

### Response

```json theme={null}
{
  "results": [
    {
      "winners": [
        {
          "rank": 1,
          "type": "product",
          "id": "p_Mfk15",
          "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0="
        },
        {
          "rank": 2,
          "type": "product",
          "id": "p_PJbnN",
          "resolvedBidId": "WyJlX1BKYm5OIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0="
        }
      ],
      "error": false
    }
  ]
}
```

Notable comments:

* The type of the winners is `product`, because we're running a listings auction.
* There are two winners, the maximum that is allowed by the `slots` field in the request.
* The winner in rank 1 `"p_Mfk15"` comes from the set of product and rank 2 `"p_PJbnN"` comes from matching keywords
  since its `id` was not specified in the auction request.

<Note>
  Running auctions using the `searchQuery` parameter enhances Topsort to improve
  the Keywords Matching algorithm.
</Note>

<Warning>
  Using this type of auctions does not allow to use **quality scores**.
</Warning>

## Next steps

The winners will need to be combined with product data to a create a result that can be shown to the end-user.

Check [this page](/en/api-reference/examples/sponsored-listings/combining-results) for an example.