Google Ads API is returning to beta status. Please read our blog post for more details.

Matching Functions

Matching functions are the mechanism by which you tell Google Ads which set of data in your feeds to use in which contexts when serving ads. A MatchingFunction consists of three fields: left_operands, operator, and right_operands. For example, a matching function that wants to restrict to feed items with IDs of 1, 2, and 3 would have a left_operands specifying a request context of FEED_ITEM_ID, an operator of IN, and a right_operands specifying the set of IDs you want to restrict to: [1, 2, 3].

Alternatively, you can use a function_string to create an equivalent function:

IN(FEED_ITEM_ID,{1,2,3})

Function types

The following functions are allowed as leaf nodes, either at the top level or after combining functions (shown in the next section).

Platform

Use this function to limit display of specific ad extensions to specific platforms (mobile or desktop).

Field Valid Values
left_operands RequestContextOperand with context_type = DEVICE_NAME
operator EQUALS
right_operands a single ConstantOperand with string_value either Mobile or Desktop (case-sensitive)
Function string example
EQUALS(CONTEXT.DEVICE,"Mobile")

Feed item ID

Use this function to select specific feed items to serve.

Field Valid Values
left_operands RequestContextOperand with context_type = FEED_ITEM_ID
operator EQUALS or IN
right_operands one or more ConstantOperands
  • must be exactly 1 ConstantOperand for EQUALS
  • max of 20 ConstantOperands for IN
Function string example
IN(FEED_ITEM_ID,{1,2,3})

Feed attribute

Use this function to select feed items based on the value of a specific one of its attributes.

In the example below, the feed_id is 12345678, and the feed_attribute_id is 0.

Field Valid Values
left_operands FeedAttributeOperand with feed_id and feed_attribute_id set
operator EQUALS or CONTAINS_ANY
right_operands one or more ConstantOperands
  • must be exactly one ConstantOperand for EQUALS
  • maximum of three ConstantOperands for CONTAINS_ANY
Function string example
CONTAINS_ANY(FeedAttribute[12345678,0],{"Mars cruise","Venus cruise","Moon cruise"})

Identity functions

Identity functions are always true or always false. This can be useful for matching every feed item within a feed.

Field Valid Values
left_operands exactly one ConstantOperand with its boolean_value set to true or false
operator IDENTITY
rhsOperand none
Function string example
IDENTITY(true)

Combining functions

You can use the AND operator to logically combine two or more functions to form a new matching function.

Field Valid Values
left_operands At least two FunctionOperand objects
operator AND
right_operands none
Function string example
AND(IN(FEED_ITEM_ID,{1,2,3}),EQUALS(CONTEXT.DEVICE,"Mobile"))

When combining functions, the left_operands can include:

  • Either:
    • One or more feed item ID functions OR
    • One or more feed attribute functions
  • AND (optional) at most one platform function

You can only use an AND operator at the top level; you cannot nest functions further than one level deep.

Operator rules

Each operator has specific rules that must be followed.

  • IN - The right_operands must contain at least 1 and no more than 20 ConstantOperand objects.
  • EQUALS - The right_operands must contain exatly 1 ConstantOperand object.
  • AND - The left_operands must contain at least 2 FunctionOperand objects. The right_operands should not be set.
  • CONTAINS_ANY - The right_operands must contain at least 1 and no more than 3 ConstantOperand objects.
  • IDENTITY - The left_operands must contain exactly 1 ConstantOperand with its boolean_value set. The right_operands should not be set.

Restrictions

CustomerFeed supports any placeholder type except CALL and MESSAGE.

CustomerFeed with location extensions only supports a true IDENTITY function or a platform function; no other matching functions will be accepted.

For CampaignFeed and AdGroupFeed, you can use all the function types and function combinations outlined above without additional restriction.