# Requesting a Search Term Product Ad

Search term ads are typically the easiest to request. They require a simple "context' to be sent to Project Agora Commerce. A "context" is a bit of code that defines the conditions under which a product is shown to a customer.

### Minimum Viable Context:

Below are the minimum values needed to generate a search term ad:

{% tabs %}
{% tab title="HTTP" %}

```yaml
POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic your_api_key_here
{
    "catalogId": "$MY_CATALOG_ID",
    "searchTerm": "string",
    "placement": "sponsoredproducts",
    "maxNumberOfAds": number,
    "sessionId": "string"
}
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl -iX POST "$BASE_URL/v1/ads/generate" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic your_api_key_here" \
-d \
'{
    "catalogId": "$MY_CATALOG_ID",
    "searchTerm": "string",
    "placement": "sponsoredproducts",
    "maxNumberOfAds": number,
     "sessionId": "string"
}'
```

{% endtab %}
{% endtabs %}

### Exemplar Context

Here is an example of a context for the `pageType "Search"`:

{% tabs %}
{% tab title="HTTP" %}

```yaml
POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "Wine",
    "placement": "sponsoredproducts",
    "maxNumberOfAds": 3,
      "sessionId": "23dn3923-323d"
}
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl -iX POST "$BASE_URL/v1/ads/generate" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8" \
-d \
'{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "Wine",
    "placement": "sponsoredproducts",
    "maxNumberOfAds": 3,
     "sessionId": "23dn3923-323d"
}'
```

{% endtab %}
{% endtabs %}

### **What Happens when an Ad Is Successfully Requested**

When you successfully request an ad, you receive the following object:

{% tabs %}
{% tab title="HTTP" %}

```yaml
HTTP/2 200
{
    "ads": [
        {
            "id": "display_SEY2W7-VZzspoirbw4ANs-r-w6YyODk5MDQ5UA==",
            "gtin": "catpref--2899049P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:46:07.516943179Z"
        },
        {
            "id": "display_-hPcUdg5KUQ2sxhE6r0XVN3-iLY5ODkxNTY2UA==",
            "gtin": "catpref--9891566P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:46:07.516948637Z"
        },
        {
            "id": "display_aGULlK-E_yEiVZ_S_jH9qsH-KhYyOTAyNjIwUA==",
            "gtin": "catpref--2902620P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:46:07.516953955Z"
        }
    ],
    "banners": [],
    "products": []
}
```

{% endtab %}

{% tab title="cURL" %}

```yaml
"ads": [
        {
            "id": "display_SEY2W7-VZzspoirbw4ANs-r-w6YyODk5MDQ5UA==",
            "gtin": "catpref--2899049P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:46:07.516943179Z"
        },
        {
            "id": "display_-hPcUdg5KUQ2sxhE6r0XVN3-iLY5ODkxNTY2UA==",
            "gtin": "catpref--9891566P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:46:07.516948637Z"
        },
        {
            "id": "display_aGULlK-E_yEiVZ_S_jH9qsH-KhYyOTAyNjIwUA==",
            "gtin": "catpref--2902620P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:46:07.516953955Z"
        }
    ],
    "banners": [],
    "products": []
}
```

{% endtab %}
{% endtabs %}

No customer information or cart items are necessary in this simple context. The simple context consists only of search terms and necessary filters.

In order to properly integrate the Search Term Product Listing ad request the `searchTerm` value shall contain a variable which is used in the search bar of the website's search page and is filled by user input.

This ensures that the ad request is being executed in every case with the value that users enters in the search bar, so that relative ads will show up.

{% hint style="info" %}
The `discount` and `products` fields are legacy and can be ignored
{% endhint %}

{% hint style="info" %}
The placement`sponsoredproducts should be included in all SPL requests`
{% endhint %}

{% hint style="info" %}
In gtin field of the above responses you will get the pa\_id as in the product feed for the product to be displayed. 

**Reminder**: the pa\_id is the concatenation of the catalog prefix and each product SKU, so to identify which SKU to display on your side you may need to remove the catalog prefix and the symbols "--"

pa\_id= catprefix--**SKU**
{% endhint %}

### Filtered Searches

When a user filters their browsing deeper, you are able to serve ads relevant to their filters using `productFilters` in the context.

In this example, the user has navigated to the Red Wine category within their search, and filtered their browsing to  "Shiraz" Red Wines. This is a new request and considered by Project Agora Commerce as a new page, and new set of ads. Even in the rare event the ads served are identical to the unfiltered results.

{% tabs %}
{% tab title="HTTP" %}

```yaml
POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "Wine",
        "productFilters": [
      ["taxonomy:RedWine>Shiraz"]
    ],
    "placement": "sponsoredproducts",
    "maxNumberOfAds": 3,
     "sessionId": "23dn3923-323d"
}
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl -iX POST "$BASE_URL/v1/ads/generate" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8" \
-d \
'{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "Wine",
        "productFilters": [
      ["taxonomy:RedWine>Shiraz"]
    ],
    "placement": "sponsoredproducts",
    "maxNumberOfAds": 3,
     "sessionId": "23dn3923-323d"
}'
```

{% endtab %}
{% endtabs %}

As your customers filter deeper in their searches, your request will include more product filters

{% tabs %}
{% tab title="HTTP" %}

```yaml
POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "Wine",
        "productFilters": [
       ["taxonomy:RedWine>Shiraz", "Type:Australia", "delivery:DeliveryOnly", "pricerange:$25-$50"]
    ],
    "placement": "sponsoredproducts",
    "maxNumberOfAds": 5,
     "sessionId": "23dn3923-323d"
}
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl -iX POST "$BASE_URL/v1/ads/generate" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8" \
-d \
'{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "Wine",
        "productFilters": [
       ["taxonomy:RedWine>Shiraz", "Type:Australia", "delivery:DeliveryOnly", "pricerange:$25-$50"]
    ],
    "placement": "sponsoredproducts",
    "maxNumberOfAds": 5,
     "sessionId": "23dn3923-323d"
}'
```

{% endtab %}
{% endtabs %}

### **What Happens when an Ad Is Successfully Requested**

When you successfully request an ad, you receive the following object:

{% tabs %}
{% tab title="HTTP" %}

```yaml
HTTP/2 200
{
    "ads": [
       {
            "id": "display_ZFwfo0Mi2AhFBxUBHpXnICvV2j8zNTcxNzExUA==",
            "gtin": "catpref--3571711P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:51:07.936105529Z"
        },
        {
            "id": "display_VpFfnPOnaG4MZh43ckQjufmGAzwzNTcxOTkyUA==",
            "gtin": "catpref--3571992P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:51:07.936111787Z"
        },
        {
            "id": "display_vRHRnkTXbbssVwiem8jDrmOp2FM2Mzg3NTkyUA==",
            "gtin": "catpref--6387592P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:51:07.936117921Z"
        },
    ],
    "banners": [],
    "products": []
}
```

{% endtab %}

{% tab title="cURL" %}

```yaml
{
    "ads": [
       {
            "id": "display_ZFwfo0Mi2AhFBxUBHpXnICvV2j8zNTcxNzExUA==",
            "gtin": "catpref--3571711P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:51:07.936105529Z"
        },
        {
            "id": "display_VpFfnPOnaG4MZh43ckQjufmGAzwzNTcxOTkyUA==",
            "gtin": "catpref--3571992P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:51:07.936111787Z"
        },
        {
            "id": "display_vRHRnkTXbbssVwiem8jDrmOp2FM2Mzg3NTkyUA==",
            "gtin": "catpref--6387592P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:51:07.936117921Z"
        },
    ],
    "banners": [],
    "products": []
}
```

{% endtab %}
{% endtabs %}

### Filtered Search with Brands

When a brand menu is available as a filtering option in the search page of the website, then the SPL requests shall respond according to the user input (the option that he will choose from the menu) and the rendering of the SPL grid should be handled by new SPL requests.

If multiple options are selected from the menu then the request shall be handled as in the below example.

In this example the user is navigating in the search page with the search term "Wine" and he chooses as a filter the brands "brand1" and "brand2""

```
"searchTerm": "Wine"
"productFilters": [
      ["brand:brand1"],["brand:brand2"]
    ],
```

**Please note that two attributes separated with the "," character inside brackets \[], are handled with an OR logic while the character "," outside the brackets, is connected among different objects with the AND logic**.

In the above example, the request translates as: render an SPL item coming from a search query with the search term "Wine" which belongs to either one from the brands "brand1" and "brand2"

The above query can be enhanced further with a category filter. For example there might be a category menu also in the search page which narrows down the results of the search query.

In that case if for example the category "Woman>Face" was chosen by the user then the body of the request shall be modified as below:

```
"searchTerm": "Wine"
"productFilters": [
      ["brand:brand1","taxonomy:Woman>Face"],["brand:brand2","taxonomy:Woman>Face"]
    ],
```

### SPL items when Sorting is used

Please note that when the user chooses the option to sort the products on the website, the page should be rendered without showing any SPL item so that there won't be any disruption on the sorting functionality and user experience

### Enabling Google Analytics tracking for SPL items

In order to start having recordings in your Google Analytics account for the SPL items you will have to add the following utm parameter in the landing url of an SPL item:

```
utm_source=pacommerce&utm_medium=spl
```

{% hint style="info" %}
`sessionId` is needed to be included in the ad request as it will be used later in order reporting. For more information please check the "Syncing Order Data" page
{% endhint %}

{% hint style="info" %}
If you are unsure of the strings displayed on this page. Take a look at the Reference page.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers-commerce-v2.projectagora.com/integration-guides/product-listing-ad-integration-guide/requesting-a-search-term-product-ad.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.