Supported Targeting Types

The targeting object supports the following targeting types.

Supported JSON Schemas

Our API supports two distinct JSON schemas for defining targeting: Expression-Based (Legacy nested JSON structure) and the Flattened Structure (new).

• The Expression-Based Structure (Legacy): The Expression-Based Structure is the legacy structure,using nested logical operators . In this structure, the root must be an and array. Negative targeting (exclusions) must be wrapped inside a not array, which itself is nested inside the root and array
• The Flattened Structure (New): The Flattened Structure is the new flattened schema. Instead of requiring you to build complex logical trees (AND/NOT), you simply define arrays of items you want to include or exclude

You must use only one structure in a single Create or Update request payload. Mixing expression-based and flattened targeting structures in the same request is not supported.

Key Rules

• You may define exactly one primary tactic: keywords, contextual, behavioral, or runOfSite .
• You may optionally combine your primary tactic with geoTargets
• Negative targeting is supported only for keywords and behavioral. In the Expression-Based Structure, use not. In the Flattened Structure, use exclude
• Within each include or exclude array, values are evaluated using OR logic. Exclusions are then applied against the included set. For example: include (1 OR 2 OR 3) AND exclude (5 OR 6 OR 7)

Retrieving targeting in Flat Format

For supported read APIs, you can retrieve targeting details in the flattened structure by passing the following request header: x-targeting-format: FLAT

This header is used only to control the response format for supported read APIs, such as:

• List Ad Groups
• Entity Snapshot API - line item snapshot

Supported Values:

If the x-targeting-format header is not included, targeting is returned using the expression-based structure by default.

Create, Update, and Forecasting APIs do not require the x-targeting-format header. These APIs can accept either the expression-based structure or the flattened structure in the request payload.

Request Fields by Targeting Type

keywords

• Keyword targeting allows ads to be shown to users searching for relevant terms.
• Keyword targeting is not supported for Video campaigns.

Notes:

• negative keyword targeting is supported
• excluded, or negative, keywords support only EXACT match

contextual

Contextual targeting places ads on pages relevant to selected product categories.

Reach tier mapping:

Notes:

• Negative contextual targeting is not supported.
• Do not use not or exclude for contextual targeting.
  

behavioral

Behavioral targeting reaches users based on previous shopping behavior, intent signals, or audience attributes.

Notes:

• Negative behavioral targeting is supported.
• Use not in the Expression-Based Structure.
• Use exclude in the Flattened Structure

runOfSite

Run-of-site targeting allows the ad to run site-wide without a primary behavioral, contextual, or keyword targeting tactic.

Notes:

• If runOfSite is set to true, no other primary targeting type may be defined.
• runOfSite may be combined with geoTargets if geographic restrictions are required.

geoTargets

Geo targeting restricts ad delivery to a specific geographic area.

If geoTargets is omitted, targeting defaults to the United States.

You cannot combine different geo-targeting types within a single ad group.

Supported geo targeting options:

Example structure:

keywords (Expression Structure)

"targeting": { "and": [ { "and": [ { "keywords": [ { "keywordText": "running shoes", "matchType": "BROAD" } ] }, { "not": [ { "keywords": [ { "keywordText": "trail sneakers", "matchType": "EXACT" } ] } ] } ] }, { "geoTargets": [{ "id": 123} ]} ]
}

keywords (Flattened Structure)

"targeting": { "keywords": { "include": [ { "matchType": "EXACT", "keywordText": "running shoes" }, ], "exclude": [ { "matchType": "EXACT", "keywordText": "trail sneakers" } ] }, "geoTargets": { "include": [ {"id": 123} ] }
} 

contextual (Expression Structure)

"targeting": { "and": [ { "contextual": [{"id": 101, "reach": "tier_1"}] }, { "geoTargets": [{"id": 123}] } ]
} 

contextual (Flattened Structure)

"targeting": { "contextual": { "include": [{"id": 101, "reach": "tier_1"}] } }, "geoTargets": { "include": [ {"id": 123} ] }
} 

behavioral (Expression Structure)

"targeting": { "and": [ { "and": [ { "behavioral": [{ "id": 200, "audienceType": "RETAIL", "attribute": "HISTORICAL" }] }, { "not": [{ "behavioral": [{ "id": 201, "audienceType": "RETAIL", "attribute": "HISTORICAL" }] }] } ] }, { "geoTargets": [{ "id": 123 }] } ]
} 

behavioral( Flattened Structure)

"targeting": { "behavioral": { "include": [{ "id": 200, "audienceType": "RETAIL", "attribute": "HISTORICAL" }], "exclude": [{ "id": 201, "audienceType": "RETAIL", "attribute": "HISTORICAL" }] } }, "geoTargets": { "include": [ {"id": 123} ] }
} 

runOfSite (Expression Structure)

"targeting": { "and": [ { "runOfSite": true }, { "geoTargets": [ { "id": 123 } ] } ]
}

runOfSite (Flattened Structure)

"targeting": { "runOfSite": true , "geoTargets": { "include": [ { "id": 123 } ] }
} 

geoTargets (Expression Structure) - using id:

{ "geoTargets": [ { "id": 123 } ] }

geoTargets (Expression Structure) - using zipCode:

{ "geoTargets": [ { "zipCode": "94001" } ] }

geoTargets (Flattened Structure) - using id:

{ "geoTargets": "include":[{ "id": 123 }]
}

geoTargets (Flattened Structure) - using zipCode:

{ "geoTargets": "include":[{ "zipCode": "94001" }]
}

List Response Metadata

When targeting is returned by the List Ad Groups API or Line item entity snapshot, the targeting object may include additional metadata fields to help developers display, audit, or map targeting values in partner systems.

These fields are returned in responses and should be treated as response metadata. Do not include response-only metadata fields in Create or Update request payloads unless the endpoint documentation explicitly allows them.

contextual response fields

behavioral response fields

keywords response fields

geoTargets response fields

Returns different fields depending on the geo targeting type used.

If state, city, DMA, or country targeting is used, the response includes id, name, and locationType

If zip code targeting is used, the response includes zipCode.

Forecasting API Behavior

Forecasting APIs can accept targeting inputs using either the Expression-Based Structure or the Flattened Structure. If targeting values are provided in a forecasting request, the forecast is based on the request targeting values, not on any existing ad group targeting settings.

• Use only one targeting schema per request payload.
• Do not mix expression-based and flattened structures in the same payload.
• Define exactly one primary tactic: keywords, contextual, behavioral, or runOfSite.
• Optionally combine the primary tactic with geoTargets.
• Do not combine different geo-targeting types within a single ad group.
• Use negative targeting only with keywords and behavioral.
• Use not only in the Expression-Based Structure.
• Use exclude only in the Flattened Structure.
• Treat additional fields returned by List Ad Groups and line item snapshot, such as name, mappingType, and reviewStatus, as response metadata.