Algorithms

Emission algorithms determine how ads are selected for specific ad units. Each ad unit can have a specific algorithm assigned that decides the search strategy and ranking of products or banners.

Sponsored Product Algorithms

Bestseller

Algorithm that selects popular products based on popularity metrics.

Required parameters:

slotHash - ad unit identifier
adCount - number of ads to return

Optional parameters:

searchData - search phrase for filtering
categories / categoryPaths - categories for filtering
productTitle - product title to consider
excludedShopProductIds - products to exclude
priceMin / priceMax - price range
currency - currency
brand - brand
attributes - additional attributes
adType - ad type (ALL/AUTOPROMO/SPONSORED)

Note: BESTSELLERS_WIDE variant ignores filtering by priceMin/priceMax, brand, categoryPaths or attributes.

POST https://dispatcher.ahevds.com/v1/dsa/raw/batch HTTP/2
Content-Type: application/json
cid: {cid}
uid: {uid}

{
  "targeting": [
    {
      "slotHash": "a64bb352-32c4-4742-8108-f6fd3358e4e3",
      "adCount": 3,
      "searchData": "toys",
      "categoryPaths": ["Kids > Toys"]
    }
  ]
}

curl --location --request POST 'https://dispatcher.ahevds.com/v1/dsa/raw/batch' \
    --header 'Content-Type: application/json' \
    --header 'cid: {cid}' \
    --header 'uid: {uid}' \
    --data-raw '{
      "targeting": [
        {
          "slotHash": "a64bb352-32c4-4742-8108-f6fd3358e4e3",
          "adCount": 3,
          "searchData": "toys",
          "categoryPaths": ["Kids > Toys"]
        }
      ]
    }'

Context match

Algorithm that matches products based on search phrases and/or categories.

Required parameters:

slotHash - ad unit identifier
adCount - number of ads to return
searchData OR (categories / categoryPaths) - either searchData or categories is required (at least one parameter)

Optional parameters:

excludedShopProductIds - products to exclude
priceMin / priceMax - price range
currency - currency
brand - brand
attributes - additional attributes
adType - ad type

Validation: Either search phrase OR categories is required (at least one parameter).

Note: WIDE variant has no validation requirements - all parameters are optional.

POST https://dispatcher.ahevds.com/v1/dsa/raw/batch HTTP/2
Content-Type: application/json
cid: {cid}
uid: {uid}

{
  "targeting": [
    {
      "slotHash": "a64bb352-32c4-4742-8108-f6fd3358e4e3",
      "adCount": 2,
      "searchData": "cat food",
      "categoryPaths": ["Pets > Cats > Food"]
    }
  ]
}

curl --location --request POST 'https://dispatcher.ahevds.com/v1/dsa/raw/batch' \
    --header 'Content-Type: application/json' \
    --header 'cid: {cid}' \
    --header 'uid: {uid}' \
    --data-raw '{
      "targeting": [
        {
          "slotHash": "a64bb352-32c4-4742-8108-f6fd3358e4e3",
          "adCount": 2,
          "searchData": "cat food",
          "categoryPaths": ["Pets > Cats > Food"]
        }
      ]
    }'

Products with similar categories and titles

Algorithm that finds products similar to the current one based on title analysis.

Required parameters:

slotHash - ad unit identifier
adCount - number of ads to return
productTitle - reference product title

Optional parameters:

excludedShopProductIds - products to exclude
priceMin / priceMax - price range
currency - currency
brand - brand
categories / categoryPaths - categories for filtering
attributes - additional attributes
adType - ad type

POST https://dispatcher.ahevds.com/v1/dsa/raw/batch HTTP/2
Content-Type: application/json
cid: {cid}
uid: {uid}

{
  "targeting": [
    {
      "slotHash": "a64bb352-32c4-4742-8108-f6fd3358e4e3",
      "adCount": 4,
      "productTitle": "Large Toy Basket - Silver Mint",
      "excludeShopProductsIds": ["BAS-FOR-TOY-SIL-MIN"]
    }
  ]
}

curl --location --request POST 'https://dispatcher.ahevds.com/v1/dsa/raw/batch' \
    --header 'Content-Type: application/json' \
    --header 'cid: {cid}' \
    --header 'uid: {uid}' \
    --data-raw '{
      "targeting": [
        {
          "slotHash": "a64bb352-32c4-4742-8108-f6fd3358e4e3",
          "adCount": 4,
          "productTitle": "Large Toy Basket - Silver Mint",
          "excludeShopProductsIds": ["BAS-FOR-TOY-SIL-MIN"]
        }
      ]
    }'

Products with similar titles

Required parameters:

slotHash - ad unit identifier
adCount - number of ads to return
productTitle - reference product title

Optional parameters:

excludedShopProductIds - products to exclude
priceMin / priceMax - price range
currency - currency
brand - brand
categories / categoryPaths - categories for filtering
attributes - additional attributes
adType - ad type

Products with similar categories

Algorithm that finds similar products based on categories.

Required parameters:

slotHash - ad unit identifier
adCount - number of ads to return
categories OR categoryPaths - reference categories

Optional parameters:

productTitle - product title to consider
excludedShopProductIds - products to exclude
priceMin / priceMax - price range
currency - currency
brand - brand
attributes - additional attributes
adType - ad type

Similar products (by product id)

Algorithm that finds products similar to a specific product by ID.

Required parameters:

slotHash - ad unit identifier
adCount - number of ads to return
productId - reference product ID. We accept both g:id and ah:productId from feed.

Optional parameters:

excludedShopProductIds - products to exclude
currency - currency
adType - ad type

POST https://dispatcher.ahevds.com/v1/dsa/raw/batch HTTP/2
Content-Type: application/json
cid: {cid}
uid: {uid}

{
  "targeting": [
    {
      "slotHash": "a64bb352-32c4-4742-8108-f6fd3358e4e3",
      "adCount": 3,
      "productId": "BAS-FOR-TOY-SIL-MIN"
    }
  ]
}

curl --location --request POST 'https://dispatcher.ahevds.com/v1/dsa/raw/batch' \
    --header 'Content-Type: application/json' \
    --header 'cid: {cid}' \
    --header 'uid: {uid}' \
    --data-raw '{
      "targeting": [
        {
          "slotHash": "a64bb352-32c4-4742-8108-f6fd3358e4e3",
          "adCount": 3,
          "productId": "BAS-FOR-TOY-SIL-MIN"
        }
      ]
    }'

Others also bougth

ML-based product recommendations using the recommendation engine.

Required parameters:

slotHash - ad unit identifier
adCount - number of ads to return
shopProductId - product ID for which recommendations are generated

Optional parameters:

excludedShopProductIds - products to exclude
adType - ad type

POST https://dispatcher.ahevds.com/v1/dsa/raw/batch HTTP/2
Content-Type: application/json
cid: {cid}
uid: {uid}

{
  "targeting": [
    {
      "slotHash": "a64bb352-32c4-4742-8108-f6fd3358e4e3",
      "adCount": 5,
      "shopProductId": "BAS-FOR-TOY-SIL-MIN"
    }
  ]
}

curl --location --request POST 'https://dispatcher.ahevds.com/v1/dsa/raw/batch' \
    --header 'Content-Type: application/json' \
    --header 'cid: {cid}' \
    --header 'uid: {uid}' \
    --data-raw '{
      "targeting": [
        {
          "slotHash": "a64bb352-32c4-4742-8108-f6fd3358e4e3",
          "adCount": 5,
          "shopProductId": "BAS-FOR-TOY-SIL-MIN"
        }
      ]
    }'

External matching (EXACT_PRODUCT_ID)

Algorithm that searches for exactly specified products based on ID list.

Required parameters:

slotHash - ad unit identifier
adCount - number of ads to return
productIds - array of product IDs (maximum 100 elements). We accept both g:id and ah:productId from feed.

Optional parameters:

excludedShopProductIds - products to exclude
priceMin / priceMax - price range
currency - currency
brand - brand
categories / categoryPaths - categories for filtering
attributes - additional attributes
adType - ad type

Validation: productIds list is required and can contain maximum 100 elements.

POST https://dispatcher.ahevds.com/v1/dsa/raw/batch HTTP/2
Content-Type: application/json
cid: {cid}
uid: {uid}

{
  "targeting": [
    {
      "slotHash": "a64bb352-32c4-4742-8108-f6fd3358e4e3",
      "adCount": 2,
      "productIds": [
        "BAS-FOR-TOY-SIL-MIN",
        "BAS-FOR-TOY-BLU-MIN"
      ]
    }
  ]
}

curl --location --request POST 'https://dispatcher.ahevds.com/v1/dsa/raw/batch' \
    --header 'Content-Type: application/json' \
    --header 'cid: {cid}' \
    --header 'uid: {uid}' \
    --data-raw '{
      "targeting": [
        {
          "slotHash": "a64bb352-32c4-4742-8108-f6fd3358e4e3",
          "adCount": 2,
          "productIds": [
            "BAS-FOR-TOY-SIL-MIN",
            "BAS-FOR-TOY-BLU-MIN"
          ]
        }
      ]
    }'

Banner Ad Algorithms

DISPLAY

Basic banner display algorithm with comprehensive targeting.

Required parameters:

slotHash - ad unit identifier
adCount - number of ads to return
country - country code (only validated as required)

Optional parameters:

searchData - search phrase
currency - currency
productTitle - product title
productId - product ID in context
categoryPaths - category paths
brand - brand
profiles - user profiles
adType - ad type
adFormatIds - ad format IDs

Additional: Supports Referer header for URL-based targeting.

POST https://dispatcher.ahevds.com/v1/banner/dsa/raw/batch HTTP/2
Content-Type: application/json
cid: {cid}
uid: {uid}

{
  "targeting": [
    {
      "slotHash": "8cc4ba26-bb96-46f1-975c-a6a21243bb05",
      "adCount": 1,
      "country": "PL",
      "searchData": "toys",
      "categoryPaths": ["Kids > Toys"]
    }
  ]
}

curl --location --request POST 'https://dispatcher.ahevds.com/v1/banner/dsa/raw/batch' \
    --header 'Content-Type: application/json' \
    --header 'cid: {cid}' \
    --header 'uid: {uid}' \
    --data-raw '{
      "targeting": [
        {
          "slotHash": "8cc4ba26-bb96-46f1-975c-a6a21243bb05",
          "adCount": 1,
          "country": "PL",
          "searchData": "toys",
          "categoryPaths": ["Kids > Toys"]
        }
      ]
    }'

DISPLAY_PHRASE_OR_CATEGORY

Banner targeting algorithm based on search phrases or categories.

Required parameters:

slotHash - ad unit identifier
adCount - number of ads to return
country - country code (only validated as required)

Optional parameters:

searchData - search phrase
categoryPaths - category paths
productId - product ID
brand - brand
profiles - user profiles
adType - ad type
adFormatIds - ad format IDs

POST https://dispatcher.ahevds.com/v1/banner/dsa/raw/batch HTTP/2
Content-Type: application/json
cid: {cid}
uid: {uid}

{
  "targeting": [
    {
      "slotHash": "8cc4ba26-bb96-46f1-975c-a6a21243bb05",
      "adCount": 2,
      "country": "PL",
      "searchData": "phones",
      "categoryPaths": ["Electronics > Phones"],
      "profiles": ["premium_client"]
    }
  ]
}

curl --location --request POST 'https://dispatcher.ahevds.com/v1/banner/dsa/raw/batch' \
    --header 'Content-Type: application/json' \
    --header 'cid: {cid}' \
    --header 'uid: {uid}' \
    --data-raw '{
      "targeting": [
        {
          "slotHash": "8cc4ba26-bb96-46f1-975c-a6a21243bb05",
          "adCount": 2,
          "country": "PL",
          "searchData": "phones",
          "categoryPaths": ["Electronics > Phones"],
          "profiles": ["premium_client"]
        }
      ]
    }'

Global Parameters

Parameters available for all algorithms:

Parameter	Description	Usage
Headers
`cid`	Client ID	All algorithms
`uid`	User ID	All algorithms
`Referer`	Page URL	Banner algorithms
Filters
`excludeShopProductsIds`	Products to exclude	Product algorithms
`priceMin` / `priceMax`	Price range	All algorithms
`currency`	Currency (ISO-4217)	All algorithms
`brand`	Brand	All algorithms
`attributes`	Additional attributes	All algorithms
`adType`	Ad type (ALL/AUTOPROMO/SPONSORED)	All algorithms
Targeting
`businessSlotId`	Business slot ID	All algorithms
`categories` / `categoryPaths`	Categories	All algorithms
`profiles`	User profiles	Banner algorithms
Meta
`lang`	Language	All algorithms
`country`	Country	All algorithms

Differences between WIDE variants

Algorithm variants with _WIDE suffix provide broader matching with more relaxed constraints:

Standard algorithms: Stricter matching criteria, higher precision
WIDE variants: Looser matching criteria, higher recall

Emission info Sponsored Products — deprecated