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

# Listings patrocinados em resultados de pesquisa

> Aprenda como usar listings patrocinados em resultados de pesquisa

O exemplo nesta página mostra como executar [leilões](/en/ad-server/auctions/auctions-api) para produtos originados de resultados de pesquisa.

Existem duas formas de executar este tipo de leilão:

* Usando o parâmetro `searchQuery`, onde apenas os lances direcionados a produtos com palavras-chave correspondentes terão a oportunidade de ganhar tais leilões.
* Usando um [conjunto de produtos](/en/api-reference/examples/sponsored-listings/set-of-products) e adicionalmente usar o parâmetro `searchQuery` para expandir a lista de lances, adicionando produtos com palavras-chave correspondentes aos do conjunto de produtos.

## Casos de uso

Executar este tipo de leilão em páginas de pesquisa permitirá que seus vendedores promovam produtos dentro dos resultados de pesquisa.

## Exemplo de chamada API

### Solicitação: usando `searchQuery`

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

A solicitação acima criará um único leilão de listings:

* Terá no máximo dois vencedores devido ao campo `slots`.
* O campo `searchQuery` determina quais palavras-chave os alvos de lance devem ter.

Apenas os lances direcionados a produtos com a palavra-chave `Running shoes` podem participar deste leilão.

### Resposta

```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
    }
  ]
}
```

Notável aqui:

* O tipo dos vencedores é `product`, porque estamos executando um leilão de listings.
* Há dois vencedores, o máximo permitido pelo campo `slots` na solicitação.

### Solicitação: combinando produtos e `searchQuery`

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

A solicitação acima criará um único leilão de listings:

* Terá no máximo dois vencedores devido ao campo `slots`.
* O campo `searchQuery` determina quais palavras-chave os alvos de lance devem ter.

Os produtos que entram neste leilão serão `"p_ojng4"`, `"p_8VKDt"`, `"p_Mfk15"` e aqueles com uma palavra-chave que corresponda a `searchQuery`.

### Resposta

```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
    }
  ]
}
```

Comentários notáveis:

* O tipo dos vencedores é `product`, porque estamos executando um leilão de listings.
* Há dois vencedores, o máximo permitido pelo campo `slots` na solicitação.
* O vencedor no rank 1 `"p_Mfk15"` vem do conjunto de produtos e o rank 2 `"p_PJbnN"` vem de palavras-chave correspondentes
  já que seu `id` não foi especificado na solicitação de leilão.

<Note>
  Executar leilões usando o parâmetro `searchQuery` melhora o Topsort para
  aprimorar o algoritmo de correspondência de palavras-chave.
</Note>

<Warning>
  Usar este tipo de leilão não permite usar **quality scores**.
</Warning>

## Próximos passos

Os vencedores precisarão ser combinados com dados de produtos para criar um resultado que possa ser exibido ao usuário final.

Consulte [esta página](/en/api-reference/examples/sponsored-listings/combining-results) para ver um exemplo.