Guides

Decision API Filtering

Suggest Edits

The Decision API allows customers to filter ads based on a variety of criteria. These filters can be passed in the request to limit the returned ad results which allows platform clients to filter ad items based on their needs.

It is important to note that using too many filters can cause Moloco’s ad server to filter out all ads. Filtering is based on fields found in the catalog feed, please see our Catalog Feed documentation for more information on catalog feed requirements.

Multiple filtering criteria are considered in an AND relationship. This means that an ad must meet all of the filtering criteria in order to be displayed. For example, if a request specifies the category and location filtering criteria, the Decision API will only return ad items that are in the specified category and location.

MCM supports the following 6 filtering criteria:

  • Category
  • Location
  • Brand
  • Delivery
  • Price
  • Sale Price

Filtering API example:

“filtering”: {  
    “category”: {...},  
    “location”: {...},  
    “brand”: {...},  
    “delivery”: {...},  
    “price”: {...},  
    “sale_price”:  {...}  
}

Category

Used to filter ads based on the categories found in the catalog feed category field

  • Category filtering uses two arguments as inputs: an operator and a list of categories.
    • The operator can have two values OR and AND. The default value is OR.
    • Categories can have multiple category values. Each category value is a multi-depth value. The exact depth of the category must be present in the category field.
      • Example: To filter ad items based on the 2nd depth of A>B>C category.
        Send A>B instead of A>B>C.
      • Example: Bag/accessories>Women>Clutch/wallet
        Filter: Bag/accessories>Women
  • The OR operator will return ad items that match any of the categories.
  • The AND operator will only return ad items that match all of the categories.

Category example:

“category”: {  
    “operator”: “or”,  
    “categories”: [“A>B>C”, “X>Y>Z”],  
}

Location

Used to filter ads based on the categories found in the catalog feed location field.

  • Each location value is a multi-depth value and may contain multiple location values. The exact depth of the location must be present in the location field.
    • Example: To filter ad items based on the 2nd depth of A>B>C category.
      Send A>B instead of A>B>C.
    • Example: US>CA>Redwoodcity;CA>SanFrancisco
      Filter: US>CA
    • Use the OR operator to combine multiple location values, the API will return ad items that match any of the locations in the list.

Location example:

“location”: {  
    “locations”: [“A>B>C”, “X>Y>Z”],  
}

Brand

Used to filter ads based on brand_id id found in the catalog feed brand_id field.

  • Brand filtering will return ad items that match the brand_id exactly.

Brand example:

“brand”: {  
    “brand_id”: “ABCDE”  
}

Delivery

Used to filter ads based on the delivery_option found in the Catalog Feed delivery_option field.

  • Delivery filtering uses one argument, delivery_option and will return ads items that match the delivery_option exactly.

Delivery example:

“delivery”: {  
    “delivery_option”: “one-day”,  
}

Price

Used to filter ad items with price between min_price and max_price, inclusive. For example, items with a price of 1000 will be returned if the “min_price” = 1000, and “max_price” = 2000.

Price filtering requires two arguments, min_price and max_price.

“price”: {  
    “min_price”: 1000.0,  
    “max_price”: 2000.0  
}

Using cutoff ranges:

Price x or more: Set “max_price” to be a large number that will cover the entire catalog of items: 

“price”: {  
“min_price”: x,  
“max_price”: 1000000000000  
}

Price y or less: Set “min_price” to 0: 

“price”: {  
	“min_price”: 0,  
	“max_price”: y  
}

Limitations

  • min_price and max_price must be the same currency as the platform's default currency and catalog.

Invalid requests

The following conditions are considered invalid and will return a 400 BAD REQUEST error:

  • “min_price” or “max_price” contains a negative number
  • “min_price” is greater than “max_price”

Sale Price

Used to filter ad items with sale price between min_sale_price and max_sale_price, inclusive.

  • Sale Price filtering uses two arguments, min_sale_price and max_sale_price.
  • Example: Items with a sale price of 1000 will be returned if the “min_sale_price” = 1000, and “max_sale_price” = 2000.
“sale_price”: {  
    “min_sale_price”: 1000.0,  
    “max_sale_price”: 2000.0  
}

Using cutoff ranges:

Sale Price x or more: Set “max_sale_price” to number that will cover the entire catalog of items: 

“sale_price”: {  
“min_sale_price”: x,  
“max_sale_price”: 1000000000000  
}

Sale Price y or less: Set “min_sale_price” to 0: 

“sale_price”:{  
“min_sale_price”: 0,  
“max_sale_price”: y  
}

Limitations

  • min_sale_price and max_sale_price must be the same currency as the platform's default currency and catalog.

Invalid requests

The following conditions are considered invalid and will return a 400 BAD REQUEST error:

  • “min_sale_price” or “max_sale_price” contains a negative number
  • “min_sale_price” is greater than “max_sale_price”

FAQ

Q. What happens when all ad items are filtered out due to filtering criteria?

The decision API will return an empty response with a status code of 200 when:

  • The filter combinations filter out all ad items.
  • There are no active ad items that match the filtering criteria.

Updated 5 months ago