AdQuery

What is AdQuery?

AdQuery is a Decision API feature that filters which ads get selected based on properties of the ads. It provides fine-grained controls on the ad request side - think of AdQuery as querying over ads in a database and returning selections that match your query.

Say a marketplace displays sponsored listings in search results. When the marketplace's users select a price range and a category in the search (like a price between 0 and 200 and a category "lawn-care"), the marketplace makes a Decision API request that queries for those prices and category. The response will only contain ads that meet those criteria. The marketplace then integrates those ads into the search as sponsored results.

AdQuery supports a range of filtering strategies — from fine-grained attribute filters (price ranges, categories, sizes) to passing candidate product lists for Auction-as-a-Service. Pair it with Kevel Catalog to automatically sync product data into your ads.

How AdQuery Works

AdQuery uses creative template field values as queryable properties. These values must be strings ("lawn-care"), numbers (24, 26.72 etc.), or arrays (["lawn-care", "tools"]).

In order to be used for AdQuery, a creative template field must have "AdQuery": true set while creating or updating the creative template.

A Kevel user sets values for those fields when creating a creative template ad in the API or UI. Using the marketplace example, each seller's product would be given a creative, and queryable details from that product would be set on the creative as values.

Once an ad is live, a Decision API request makes an ad query on a placement to return any eligible ads for that query.

Setting Up AdQuery Templates and Ads

Create a creative template with AdQuery enabled fields. OR update an existing template with new AdQuery enabled fields.

To make a field enabled for AdQuery, include the parameter "AdQuery" set to true. The Variable of the field will become the key used for the AdQuery.

Here's an example creative template with three enabled fields:

Example Template JSON

{
    "Name": "AdQuery Is Cool",
    "Description": "v1",
    "IsArchived": false,
    "Fields": [
        {
            "Name": "Product Price",
            "Description": "Product Price",
            "Required": true,
            "Variable": "ctPrice",
            "AdQuery": true,
            "Type": "Number"
        },
        {
            "Name": "Product Size",
            "Description": "Product Size",
            "Required": false,
            "Variable": "ctSize",
            "AdQuery": true,
            "Type": "String"
        },
        {
            "Name": "Product Categories",
            "Description": "Product Categories",
            "Required": false,
            "Variable": "ctCategories",
            "AdQuery": true,
            "Type": "Array"
        }
    ],
    "Contents": [
        {
            "Type": "Raw",
            "Body": "."
        }
    ]
}

curl -X POST \
     -H "X-Adzerk-ApiKey: $ADZERK_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{\
        "Name": "AdQuery Is Cool",\
        "Description": "v1",\
        "IsArchived": false,\
        "Fields": [\
          {\
          "Name": "Product Price",\
          "Description": "Product Price",\
          "Required": true,\
          "Variable": "ctPrice",\
          "AdQuery": true,\
          "Type": "Number"\
          },\
          {\
          "Name": "Product Size",\
          "Description": "Product Size",\
          "Required": false,\
          "Variable": "ctSize",\
          "AdQuery": true,\
          "Type": "String"\
          },\
          {\
          "Name": "Product Categories",\
          "Description": "Product Categories",\
          "Required": false,\
          "Variable": "ctCategories",\
          "AdQuery": true,\
          "Type": "Array"\
          }\
        ],\
        "Contents": [\
          {\
          "Type": "Raw",\
          "Body": "."\
          }\
        ]\
     }' \
     "https://api.kevel.co/v2/creative-templates"

Creating Ads for Creatives

1. Create creatives that supply values for the AdQuery enabled fields. This creative should include the TemplateId, and the AdQuery values should go in the TemplateValues. Refer to the creative endpoint docs for details.

Example Creative JSON

{
    "AdvertiserId": 12345,
    "AdTypeId": 5,
    "Title": "Price: 100 Dollars!!!",
    "IsActive": true,
    "ScriptBody": "Come buy this cool thing for a Benjamin",
    "IsHTMLJS": true,
    "TemplateId": 12345,
    "TemplateValues": "{\"ctPrice\":100}"
}

2. Create ads for those creatives to associate them with flights.

Setting Up AdQuery Decision API Requests

Make your ad queries in the adQuery key on the placements object. The key for the query is the Variable name of the creative template field.

You can request one or more fields to query:

Example Decision Request JSON

{
    "placements": [
        {
            "networkId": 12345,
            "siteId": 12345,
            "adTypes": [
                5
            ],
            "adQuery": {
                "ctPrice": {
                    "min": 50,
                    "max": 250,
                    "nullValuesMatch": false
                },
                "ctSize": {
                    "eq": "large",
                    "nullValuesMatch": false
                },
                "ctCategories": {
                    "eq": 136933,
                    "nullValuesMatch": false
                }
            }
        }
    ]
}

Using Arrays

Kevel customers may have Creative Template fields that have multiple sets (or ‘arrays’) of product data (eg SKU, price, brand, category). One product may belong to multiple categories in the customer's catalog and is often represented as an array of category ids.

For example, a Creative's data may be "ctCategories": ["cat1","cat7","cat8"].

In an ad decision request, a Kevel customer will pass the current category of the page which ads are to be shown. AdQuery can also support returning ads for products when the category is not the only category the product belongs to.

Phrase or Fuzzy Matching

AdQuery supports phrase matching on string fields. This is commonly used to match user search terms (that may contain slight misspellings or snippets of longer product names) against product details. Phrase matching is based on a lexical edit distance and phonetic algorithms.

Operators

🚧

If an ad query isn't present on a Decision API request, and ad query eligible ads are candidates for that decision, any of the ad query eligible ads will be returned.

What’s Next

• Auction-as-a-Service: Using AdQuery to Run Ads Against Your Own Candidate Sets
• Relevancy Score