AdCP — Targeting

AdCP’s targeting philosophy centers on brief-based targeting where targeting requirements are communicated through natural language briefs, and publishers return products that include all necessary targeting capabilities.

Core Principle: Targeting Through Briefs

The primary way to specify targeting in AdCP is through campaign briefs. Instead of configuring complex targeting parameters, buyers describe their audience requirements in plain language:

{
  "brief": "We want to reach millennial parents (ages 25-40) in major US metro areas who are interested in sustainable products. Focus on mobile and desktop during evening hours when families are planning purchases."
}

Publishers then return products that include the targeting capabilities to reach this audience, with targeting costs built into the media pricing.

Why Brief-Based Targeting?

Eliminates Targeting Conflicts

Single source: All targeting comes from the publisher’s product definition
No layering conflicts: Avoids multiple targeting systems competing
Pricing consistency: Targeting costs are transparent and included in media prices

Simplifies Implementation

Natural language: Buyers describe needs in familiar terms
Publisher expertise: Publishers know their inventory and audience capabilities best
Reduced complexity: No need to learn platform-specific targeting syntax

Enables Accurate Pricing

Inclusive pricing: All targeting costs are built into the product price
No surprises: Buyers know the complete cost upfront
Market-driven: Pricing reflects true market value of targeted inventory

Real-Time Decisioning with AXE

For targeting decisions that must happen at impression time, buyers can use the Agentic eXecution Engine (AXE). AXE is the real-time execution layer between orchestrators and decisioning platforms. Key capabilities:

Dynamic audience targeting: Bring your own DMP/CDP segments to publisher inventory
Brand suitability enforcement: Real-time content evaluation and blocking
Cross-campaign frequency: Manage user exposure across multiple publishers
First-party data activation: Use your customer data without sharing PII

When to use AXE:

Audience segments that can’t be expressed in a brief
Suppression lists (existing customers, past converters)
Real-time brand suitability beyond static rules
High-cardinality targeting (millions of segment members)

See the AXE documentation for implementation details.

How Publishers Include Targeting

Publishers incorporate targeting capabilities directly into their product definitions:

Geographic Targeting

Products specify geographic coverage:

"Chicago metro premium display package" 
"US national mobile video inventory"
"California lifestyle sites network"

Demographic Targeting

Audience characteristics are built into products:

"Millennial-focused social media placements"
"Premium business professional network"
"Family-oriented content sites"

Contextual Targeting

Content alignment is inherent in product descriptions:

"Sports content premium video inventory"
"Financial news site network"
"Entertainment property display package"

Device & Platform Targeting

Technical specifications included in product format:

"Mobile-optimized video formats"
"Connected TV premium inventory"
"Desktop display network"

Brief Examples for Common Targeting Needs

Geographic Targeting

{
  "brief": "Target users in New York, Los Angeles, and Chicago metro areas with premium display advertising for our luxury retail brand."
}

Demographic Targeting

{
  "brief": "Reach parents with children under 10 who are interested in educational content, focusing on weekend and evening viewing times."
}

Contextual Targeting

{
  "brief": "Place financial services ads adjacent to business and investment content, targeting affluent professionals during business hours."
}

Behavioral Targeting

{
  "brief": "Target users who have shown interest in sustainable products and eco-friendly brands, particularly those researching major purchases."
}

Product Response Targeting Information

When publishers return products, they include targeting information buyers need:

{
  "product_id": "premium_millennial_mobile",
  "name": "Premium Millennial Mobile Package",
  "description": "Mobile display inventory targeting millennials (25-40) across lifestyle and entertainment apps in top 25 US markets",
  "targeting_description": "Ages 25-40, household income $50K+, interests in lifestyle/entertainment, mobile apps only, top 25 US metro areas",
  "audience_size": "~2.5M monthly unique users",
  "pricing": {
    "cpm": 8.50,
    "targeting_included": true
  }
}

When to Use Targeting Overlays

Targeting overlays in create_media_buy and update_media_buy are rare and should only be used for:

Geographic Restrictions

Use geo fields only for:

RCT testing: Randomized control trials requiring specific geographic splits
Regulatory compliance: Legal requirements for geographic restrictions
Product refinement: When a product spans multiple regions and you need to restrict to a subset

Inclusion fields (restrict delivery to these locations):

geo_countries: ISO 3166-1 alpha-2 country codes (e.g., ["US", "GB"])
geo_regions: ISO 3166-2 subdivision codes (e.g., ["US-CA", "GB-SCT"])
geo_metros: Structured metro areas with explicit system (e.g., nielsen_dma, uk_itl2) — not all publishers support metro-level targeting
geo_postal_areas: Structured postal areas with explicit system (e.g., us_zip, gb_outward) — not all publishers support postal-level targeting

Exclusion fields (exclude these locations from delivery):

geo_countries_exclude: Same format as geo_countries
geo_regions_exclude: Same format as geo_regions
geo_metros_exclude: Same format as geo_metros
geo_postal_areas_exclude: Same format as geo_postal_areas

Note: Inclusion and exclusion can be combined. Metro and postal targeting require specifying the classification system, enabling international support. Not all geographic granularities are supported by all publishers. Country and region are most widely supported.

Age Restrictions (Compliance)

Use for legal compliance requirements:

Alcohol advertising: Require verified 21+ in the US
Gambling/Gaming: Require verified 18+ or 21+ depending on jurisdiction
Cannabis: Require verified age per local regulations

{
  "$schema": "/schemas/3.0.0-rc.2/core/targeting.json",
  "age_restriction": {
    "min": 21,
    "verification_required": true,
    "accepted_methods": ["facial_age_estimation", "id_document", "world_id"]
  }
}

Verification methods (defined in age-verification-method.json, based on ISO/IEC 27566-1 age assurance standards):

facial_age_estimation - AI-based age estimation (Yoti, etc.)
id_document - Government ID scan
digital_id - Verified digital identity credentials
credit_card - Payment card age gate
world_id - World ID orb verification

Note: “Inferred” age (guessing from behavior/profile) is not accepted for regulatory compliance. Platforms declare their supported verification methods in get_adcp_capabilities.

Device Platform (Technical Compatibility)

Use for technical requirements:

App install campaigns: iOS-only app requires device_platform: ["ios"]
CTV campaigns: Target specific TV operating systems

{
  "$schema": "/schemas/3.0.0-rc.2/core/targeting.json",
  "device_platform": ["ios", "android"]
}

Available platforms (defined in device-platform.json, based on Sec-CH-UA-Platform standard extended for CTV):

Browser: ios, android, windows, macos, linux, chromeos
CTV: tvos, tizen, webos, fire_os, roku_os
Other: unknown

Device type (form factor)

Use for performance optimization targeting by hardware category rather than OS:

Mobile campaigns: Target all mobile devices regardless of OS
CTV campaigns: Target connected TVs across all platforms
Exclude form factors: Skip CTV for app-install campaigns

{
  "$schema": "/schemas/3.0.0-rc.2/core/targeting.json",
  "device_type": ["mobile", "tablet"]
}

Exclusion — use device_type_exclude to exclude specific form factors:

{
  "$schema": "/schemas/3.0.0-rc.2/core/targeting.json",
  "device_type_exclude": ["dooh"]
}

Available types (defined in device-type.json):

desktop, mobile, tablet, ctv, dooh, unknown

Device type vs device platform: device_type targets form factors (mobile, desktop, CTV). device_platform targets operating systems (iOS, Android, tvOS). Use device_type for performance optimization; use device_platform for technical compatibility.

Language (Localization)

Use for localization requirements:

Creative is in a specific language
Campaign targets specific language speakers

{
  "$schema": "/schemas/3.0.0-rc.2/core/targeting.json",
  "language": ["es", "en"]
}

Format: ISO 639-1 two-letter language codes (e.g., en, es, fr, de, zh).

Frequency Capping

Two frequency controls can be used independently or together: Cooldown between exposures — suppress prevents back-to-back delivery:

{
  "$schema": "/schemas/3.0.0-rc.2/core/targeting.json",
  "frequency_cap": {
    "suppress": { "interval": 60, "unit": "minutes" }
  }
}

Impression cap per entity per window — max_impressions + per + window limits total exposure:

{
  "$schema": "/schemas/3.0.0-rc.2/core/targeting.json",
  "frequency_cap": {
    "max_impressions": 5,
    "per": "households",
    "window": { "interval": 7, "unit": "days" }
  }
}

Both can be combined. The per field uses the same entity types as reach_unit on reach optimization goals — use matching values when layering a hard cap on top of a reach campaign.

Example Geographic Overlay (RCT Testing)

For RCT testing, exclusion targeting is often simpler than inclusion. Instead of listing hundreds of DMAs to include, exclude the holdout markets from a national campaign. When inclusion and exclusion are combined, exclusion fields subtract from the included set (e.g., “US minus these 3 DMAs”):

{
  "packages": [
    {
      "buyer_ref": "test_group",
      "product_id": "national_video",
      "targeting_overlay": {
        "geo_countries": ["US"],
        "geo_metros_exclude": [
          { "system": "nielsen_dma", "values": ["501", "803", "602"] }
        ]
      }
    },
    {
      "buyer_ref": "control_group",
      "product_id": "national_video",
      "targeting_overlay": {
        "geo_metros": [
          { "system": "nielsen_dma", "values": ["501", "803", "602"] }
        ]
      }
    }
  ]
}

Inclusion targeting works the same way for cases where you want to specify exact markets:

{
  "packages": [
    {
      "buyer_ref": "test_group_a",
      "product_id": "national_video",
      "targeting_overlay": {
        "geo_metros": [
          { "system": "nielsen_dma", "values": ["501", "602", "803"] }
        ]
      }
    },
    {
      "buyer_ref": "test_group_b",
      "product_id": "national_video",
      "targeting_overlay": {
        "geo_metros": [
          { "system": "nielsen_dma", "values": ["504", "505", "506"] }
        ]
      }
    }
  ]
}

What NOT to Use Targeting Overlays For

Express these in briefs instead:

Demographic preferences (age, gender, income) - “Target millennials” or “high-income households” in brief text
Device preferences - “Mobile users” or “CTV viewers” in brief text (use device_platform overlay only for technical compatibility)
Content categories - “Sports content” or “News sites” in brief text
Third-party audience segments - “Auto intenders” or “Luxury shoppers” in brief text (use signals protocol for data provider segments)
Daypart preferences - “Morning commute hours” or “prime time evening” in brief text

Overlays vs Briefs:

Use Case	Overlay	Brief
Age for compliance (alcohol, gambling)	✅ `age_restriction`
Age for audience targeting		✅ “Target millennials”
Device for app compatibility	✅ `device_platform`
Device for audience preference		✅ “Mobile users”
Language for creative localization	✅ `language`
Language for audience preference		✅ “Spanish-speaking audiences”
First-party CRM audience (retargeting, suppression)	✅ `audience_include` / `audience_exclude`
Third-party audience segment (interest targeting)		✅ “Auto intenders” in brief, or use signals protocol
Search/retail media keyword targeting	✅ `keyword_targets` / `negative_keywords`
Broad thematic intent (“people searching for shoes”)		✅ “Reach in-market shoe shoppers”
Proximity to specific coordinates (within 2hr drive of a city)	✅ `geo_proximity`
Nearby audience (“people near coffee shops”)		✅ “Reach people near coffee shops”

Why briefs work better for preferences:

Natural language captures intent more clearly
Publishers know their inventory and can target effectively
Avoids channel-specific complexity (DOOH has no browsers)
Simpler API with fewer edge cases

Available Targeting Overlay Parameters

Geographic targeting supports both inclusion (restrict to) and exclusion (exclude from) for all geo dimensions. Inclusion and exclusion fields can be combined — for example, include a country but exclude specific metros within it.

Exclusion Semantics

Exclusion without inclusion. When an exclusion field is present without a corresponding inclusion field, the exclusion applies to the product’s full geographic coverage. For example, if a product covers the entire US and the buyer specifies only geo_metros_exclude, the excluded metros are removed from the product’s national footprint. Cross-level resolution. Geographic levels form a hierarchy: country > region > metro > postal. Sellers SHOULD resolve hierarchical conflicts such that exclusion at a higher level takes precedence over inclusion at a more specific level. For example, geo_countries_exclude: ["US"] combined with geo_regions: ["US-CA"] SHOULD result in no US delivery — the country-level exclusion takes precedence. Same-value overlap. Sellers SHOULD reject requests where the same value appears in both the inclusion and exclusion field at the same level (e.g., geo_countries: ["US"] with geo_countries_exclude: ["US"]) and return a descriptive error. Capabilities. Sellers that declare geographic targeting support in get_adcp_capabilities SHOULD support both inclusion and exclusion at that level. If a seller only supports one direction, it MUST return a validation error for unsupported fields rather than silently ignoring them.

geo_countries

Description: Restrict delivery to specific countries
Format: ISO 3166-1 alpha-2 country codes
Examples: ["US", "CA"], ["GB", "FR", "DE"]
Use cases: Regulatory compliance, country-specific campaigns

geo_countries_exclude

Description: Exclude specific countries from delivery
Format: ISO 3166-1 alpha-2 country codes
Examples: ["RU", "CN"]
Use cases: Regulatory compliance, sanctions

geo_regions

Description: Restrict delivery to specific regions/states
Format: ISO 3166-2 subdivision codes
Examples: ["US-CA", "US-NY"], ["GB-SCT", "GB-ENG"]
Use cases: State-level compliance, regional testing

geo_regions_exclude

Description: Exclude specific regions/states from delivery
Format: ISO 3166-2 subdivision codes
Examples: ["US-CA"], ["CA-QC"]
Use cases: Regulatory compliance (e.g., cannabis restrictions by province), RCT holdout regions, regions where product is unavailable

geo_metros

Description: Restrict delivery to specific metro areas
Format: Array of objects, each with a system and values
Systems: nielsen_dma (US), uk_itl1 / uk_itl2 (UK), eurostat_nuts2 (EU), custom
Example: [{ "system": "nielsen_dma", "values": ["501", "803"] }]
Use cases: Local campaigns, metro-level RCT testing
Note: Seller must declare supported systems in get_adcp_capabilities

geo_metros_exclude

Description: Exclude specific metro areas from delivery
Format: Array of objects, each with a system and values
Example: [{ "system": "nielsen_dma", "values": ["602"] }]
Use cases: RCT holdout markets, competitive exclusion zones, markets where product is unavailable
Note: Seller must declare supported systems in get_adcp_capabilities

geo_postal_areas

Description: Restrict delivery to specific postal areas
Format: Array of objects, each with a system and values
Systems: us_zip, us_zip_plus_four, gb_outward, gb_full, ca_fsa, ca_full, de_plz, fr_code_postal, au_postcode, ch_plz, at_plz
Example: [{ "system": "us_zip", "values": ["10001", "10002"] }]
Use cases: Hyper-local campaigns, postal-level restrictions
Note: Seller must declare supported systems in get_adcp_capabilities

geo_postal_areas_exclude

Description: Exclude specific postal areas from delivery
Format: Array of objects, each with a system and values
Example: [{ "system": "us_zip", "values": ["90210"] }]
Use cases: RCT holdout zip codes, restricted delivery areas
Note: Seller must declare supported systems in get_adcp_capabilities

axe_include_segment

Description: AXE segment ID for inclusion targeting
Format: String segment identifier from your AXE platform
Examples: "seg_auto_intenders_q1", "audience_lapsed_buyers_30d"
Use cases: Dynamic audience targeting, first-party data activation
Details: See AXE documentation

axe_exclude_segment

Description: AXE segment ID for exclusion targeting
Format: String segment identifier from your AXE platform
Examples: "seg_existing_customers", "audience_past_converters"
Use cases: Customer suppression, frequency management
Details: See AXE documentation

audience_include

Description: Restrict delivery to users who are members of these first-party CRM audiences. Only people on the uploaded list are eligible to see the ad.
Format: Array of audience_id strings from sync_audiences
Example: ["lapsed_subscribers", "high_value_prospects"]
Use cases: Retargeting known users, loyalty campaigns targeting existing members, CRM-based inclusion on closed platforms (LinkedIn, Meta, TikTok, Google Ads)
Not for lookalike/expansion: To find new users similar to an audience, describe the intent in your campaign brief (“reach people like our existing customers”) — the seller handles expansion strategy
Prerequisite: Audiences must be registered and ready via sync_audiences before use
Note: Seller must declare support in get_adcp_capabilities

audience_exclude

Description: Suppress delivery to users who are members of these first-party CRM audiences. Matched users are excluded regardless of other targeting.
Format: Array of audience_id strings from sync_audiences
Example: ["existing_customers", "recent_purchasers"]
Use cases: Customer suppression in acquisition campaigns, excluding recent converters, suppressing opted-out users
Prerequisite: Audiences must be registered and ready via sync_audiences before use
Note: Seller must declare support in get_adcp_capabilities

frequency_cap

Description: Limit ad exposure frequency per entity. Two optional controls can be used independently or together.
Cooldown control: suppress — minimum duration between consecutive exposures to the same entity. suppress_minutes (number) is also accepted for backwards compatibility.
Impression cap: max_impressions + per + window — total impression ceiling per entity per time window. All three fields are required together.
Use cases: User experience management, ad fatigue prevention, complementing reach optimization goals with a hard ceiling
Examples: {"suppress": {"interval": 60, "unit": "minutes"}}, {"max_impressions": 5, "per": "households", "window": {"interval": 7, "unit": "days"}}

age_restriction

Description: Require minimum age for compliance
Format: Object with min (required), verification_required, and accepted_methods
Examples: {"min": 21, "verification_required": true}, {"min": 18, "accepted_methods": ["world_id"]}
Use cases: Alcohol (21+), gambling (18+), cannabis regulations
Note: Platforms declare supported verification methods in get_adcp_capabilities

device_platform

Description: Restrict to specific operating system platforms
Format: Array of platform identifiers from Sec-CH-UA-Platform standard
Examples: ["ios"], ["ios", "android"], ["tvos", "fire_os"]
Use cases: App install campaigns (iOS-only app), CTV-specific campaigns
Values: ios, android, windows, macos, linux, chromeos, tvos, tizen, webos, fire_os, roku_os

device_type

Description: Restrict to specific device form factors
Format: Array of device type identifiers
Examples: ["mobile"], ["mobile", "tablet"], ["ctv"]
Use cases: Mobile-only promotions, CTV campaigns targeting all TV platforms, excluding DOOH from certain campaigns
Values: desktop, mobile, tablet, ctv, dooh, unknown
Note: Seller must declare device_type: true in get_adcp_capabilities targeting

device_type_exclude

Description: Exclude specific device form factors from delivery
Format: Array of device type identifiers
Examples: ["dooh"], ["ctv", "dooh"]
Use cases: Exclude CTV for app-install campaigns, exclude DOOH for direct-response campaigns
Note: Supported when seller declares device_type: true in get_adcp_capabilities

language

Description: Restrict to users with specific language preferences
Format: Array of ISO 639-1 two-letter language codes
Examples: ["en"], ["es", "en"], ["zh", "ja", "ko"]
Use cases: Localized creative, language-specific campaigns

keyword_targets

Description: Target specific keywords for search and retail media platforms. Restricts delivery to queries matching the specified keywords.
Format: Array of objects with keyword, match_type (broad, phrase, or exact), and optional bid_price
Identity: Each keyword is identified by the tuple (keyword, match_type). The same keyword string with different match types are distinct targets. Duplicate pairs in a single request SHOULD be rejected by sellers.
Match types:
- broad — matches related and synonym queries
- phrase — matches queries containing the keyword phrase in order
- exact — matches the keyword query only
Per-keyword bid: The optional bid_price overrides the package-level bid_price for that keyword. Inherits the max_bid interpretation from the pricing option: when max_bid is true, this is the keyword’s bid ceiling; when false, this is the exact bid. If omitted, the package bid_price applies.
Use cases: Search campaigns, retail media sponsored products, keyword-based intent targeting
Note: Seller must declare execution.targeting.keyword_targets in get_adcp_capabilities with the supported_match_types it accepts. Only use match types the seller declares — sellers must reject unsupported match types. Use keyword_targets_add and keyword_targets_remove in update_media_buy to add or update keywords incrementally after launch. Keyword-level delivery data (by_keyword in reporting) requires reporting_capabilities.supports_keyword_breakdown: true on the product — these are independent capabilities. by_keyword is keyword-grain (one row per keyword+match_type pair), not search-term-grain.

{
  "$schema": "/schemas/3.0.0-rc.2/core/targeting.json",
  "keyword_targets": [
    { "keyword": "running shoes", "match_type": "broad", "bid_price": 0.45 },
    { "keyword": "trail running shoes womens", "match_type": "phrase", "bid_price": 0.85 },
    { "keyword": "acme cloudrunner 5", "match_type": "exact", "bid_price": 1.20 }
  ]
}

negative_keywords

Description: Exclude specific keywords from delivery. Queries matching these keywords will not trigger the ad.
Format: Array of objects with keyword and match_type (broad, phrase, or exact)
Use cases: Prevent wasteful spend on irrelevant queries, exclude competitor brand terms
Note: Seller must declare execution.targeting.negative_keywords in get_adcp_capabilities with the supported_match_types it accepts. Use negative_keywords_add and negative_keywords_remove in update_media_buy to add/remove negatives incrementally after launch.

{
  "$schema": "/schemas/3.0.0-rc.2/core/targeting.json",
  "negative_keywords": [
    { "keyword": "free", "match_type": "broad" },
    { "keyword": "used running shoes", "match_type": "phrase" }
  ]
}

store_catchments

Description: Target users within store catchment areas from a synced store catalog
Format: Array of objects, each referencing a store-type catalog synced via sync_catalogs
Required fields: catalog_id
Optional fields: store_ids (narrow to specific stores), catchment_ids (narrow to specific zones like "walk" or "drive")
Use cases: Drive-to-store campaigns, local inventory ads, proximity targeting

{
  "targeting_overlay": {
    "store_catchments": [
      {
        "catalog_id": "retail-locations",
        "store_ids": ["store_nyc_001", "store_nyc_002"],
        "catchment_ids": ["drive"]
      }
    ]
  }
}

When store_ids is omitted, all stores in the catalog are targeted. When catchment_ids is omitted, all catchment zones are targeted. The seller must declare support for store catchment targeting in get_adcp_capabilities.

geo_proximity

Description: Target users within travel time, distance, or a custom boundary around arbitrary geographic points
Format: Array of objects, each with exactly one method: travel_time + transport_mode, radius, or geometry
Required fields: lat + lng (for travel_time and radius methods), or geometry (for pre-computed boundaries)
Optional fields: label (human-readable name for the entry)
Use cases: Tourism campaigns (within 2hr drive of a city), event targeting (near a venue), airport catchment areas
Semantics: Multiple entries use OR — a user within range of any listed point is eligible. Intersects with other geo targeting fields (e.g., combining with geo_countries restricts proximity to those countries)

Travel time (isochrone) example:

{
  "targeting_overlay": {
    "geo_proximity": [
      {
        "lat": 51.2277,
        "lng": 6.7735,
        "label": "Düsseldorf",
        "travel_time": { "value": 2, "unit": "hr" },
        "transport_mode": "driving"
      }
    ]
  }
}

Radius-based example:

{
  "targeting_overlay": {
    "geo_proximity": [
      {
        "lat": 51.4700,
        "lng": -0.4543,
        "label": "Heathrow Airport",
        "radius": { "value": 30, "unit": "km" }
      }
    ]
  }
}

Pre-computed geometry example (buyer provides the polygon):

{
  "targeting_overlay": {
    "geo_proximity": [
      {
        "label": "2hr drive from Düsseldorf",
        "geometry": {
          "type": "Polygon",
          "coordinates": [[[5.87, 50.35], [8.23, 50.35], [8.23, 52.10], [5.87, 52.10], [5.87, 50.35]]]
        }
      }
    ]
  }
}

For travel time entries, the platform resolves the isochrone to a geographic boundary based on actual transportation networks. Transport modes: driving, walking, cycling, public_transport. The geometry method allows buyers who have already computed isochrones (via TravelTime, Mapbox, etc.) to pass the polygon directly — this also enables sellers without routing engines to participate. For campaigns targeting 10+ locations, consider using store_catchments with a location catalog instead, which supports ongoing management and per-location reporting. geo_proximity does not have an exclusion variant — this is by design, as excluding “everyone near a point” is rarely a meaningful targeting constraint. Sellers SHOULD enforce minimum area thresholds consistent with their privacy policies and applicable regulations. The seller must declare geo_proximity support in get_adcp_capabilities, specifying which methods (radius, travel_time, geometry) and transport modes are supported. Validated examples:

{
  "$schema": "/schemas/3.0.0-rc.2/core/targeting.json",
  "geo_proximity": [
    {
      "lat": 51.2277,
      "lng": 6.7735,
      "label": "Düsseldorf",
      "travel_time": { "value": 2, "unit": "hr" },
      "transport_mode": "driving"
    }
  ]
}

{
  "$schema": "/schemas/3.0.0-rc.2/core/targeting.json",
  "geo_proximity": [
    {
      "lat": 51.4700,
      "lng": -0.4543,
      "label": "Heathrow Airport",
      "radius": { "value": 30, "unit": "km" }
    }
  ]
}

{
  "$schema": "/schemas/3.0.0-rc.2/core/targeting.json",
  "geo_proximity": [
    {
      "label": "2hr drive from Düsseldorf",
      "geometry": {
        "type": "Polygon",
        "coordinates": [[[5.87, 50.35], [8.23, 50.35], [8.23, 52.10], [5.87, 52.10], [5.87, 50.35]]]
      }
    }
  ]
}

Benefits for Different Stakeholders

For Buyers

Simpler planning: Describe audience needs naturally
Transparent pricing: All costs included upfront
Reduced complexity: No targeting configuration required
Better outcomes: Publisher expertise optimizes delivery

For Publishers

Pricing control: Bundle targeting into product pricing
Expertise utilization: Apply knowledge of inventory and audiences
Simplified integration: Fewer technical targeting parameters
Market positioning: Differentiate through targeting capabilities

For Platforms

Reduced conflicts: Single targeting source eliminates layering issues
Cleaner implementation: Less complex targeting logic required
Better performance: Optimized for publisher inventory characteristics

Real-Time Targeting Signals

Orchestrators can provide real-time targeting signals to publishers for dynamic, high-cardinality targeting beyond what can be expressed in static overlays. These signals enable:

Brand safety - Real-time content filtering and adjacency controls
Brand suitability - Contextual alignment with brand values
Audience targeting - Dynamic audience segments updated in real-time
Contextual targeting - Page-level or moment-level targeting decisions

Real-time signals are provided through the AdCP Signals Protocol, which allows orchestrators to supply targeting data at impression time.

Key Differences: Signals vs Overlays

Signals are evaluated at impression time, not campaign setup
Signals support higher cardinality (thousands of values vs. dozens)
Signals can be updated continuously without modifying the media buy
Signals enable sophisticated contextual targeting that briefs cannot express

When to Use Real-Time Signals

✅ Use Real-Time Signals For:

Brand safety filtering (block unsafe content)
Brand suitability scoring (prefer suitable contexts)
Dynamic audience targeting (real-time segment membership)
Contextual targeting (page-level or moment-level decisions)
High-cardinality targeting (thousands of values)
Targeting that changes during campaign flight

Managing keywords after launch

Both keyword targets and negative keywords support incremental operations in update_media_buy, avoiding the need to replace the full targeting_overlay:

keyword_targets_add — upserts by (keyword, match_type) identity. Adds new keywords or updates bid_price on existing ones.
keyword_targets_remove — removes matching (keyword, match_type) pairs.
negative_keywords_add — appends negatives. Duplicates are no-ops.
negative_keywords_remove — removes matching pairs. Missing entries are no-ops.

{
  "packages": [
    {
      "package_id": "pkg_sponsored_search_001",
      "keyword_targets_add": [
        { "keyword": "trail running shoes", "match_type": "phrase", "bid_price": 0.95 }
      ],
      "keyword_targets_remove": [
        { "keyword": "running shoes", "match_type": "broad" }
      ],
      "negative_keywords_add": [
        { "keyword": "diy", "match_type": "broad" },
        { "keyword": "how to make running shoes", "match_type": "phrase" }
      ]
    }
  ]
}

Sellers SHOULD return a validation error if targeting_overlay.keyword_targets is present in the same request as keyword_targets_add or keyword_targets_remove (and likewise for negative keywords). The incremental operations and the full overlay replacement are mutually exclusive within a single update. To remove all keyword targeting while preserving other overlay fields, send the full targeting_overlay without the keyword_targets field.

Implementation Requirements

Publishers MUST:

Support Geographic Targeting: Handle geographic inclusion and exclusion parameters (geo_countries, geo_countries_exclude, geo_regions, geo_regions_exclude, geo_metros, geo_metros_exclude, geo_postal_areas, geo_postal_areas_exclude) to the extent your platform supports them. Declare supported metro and postal systems in get_adcp_capabilities
Interpret Briefs: Use briefs to determine appropriate audience and content targeting
Validate Targeting: Reject media buys with targeting that cannot be supported
Document Limitations: Clearly communicate any geographic targeting limitations in product descriptions

Buyers SHOULD:

Use Briefs First: Express most targeting needs in natural language briefs
Minimize Overlays: Only use technical targeting for geographic restrictions or RCT testing
Trust Publishers: Let publishers apply their inventory knowledge to brief interpretation
Validate Early: Check product capabilities before applying technical targeting

Best Practices

Default to briefs - Start with natural language descriptions
Write Clear Briefs: Be specific about audience and context requirements
Trust Publisher Expertise: Publishers know their inventory capabilities best
Use signals for dynamic targeting - Real-time signals handle complex, high-cardinality targeting better than overlays
Minimize Technical Overlays: Use only for geographic restrictions or compliance
Validate Audience Fit: Ensure product descriptions match campaign goals
Inclusive pricing - Expect targeting costs to be built into product rates

Future Evolution

Enhanced Brief Processing: More sophisticated natural language understanding
Audience Discovery: Better tools for exploring available audiences
Deeper Signal Integration: More sophisticated real-time targeting capabilities
Performance Optimization: AI-driven audience refinement based on campaign results

Agentic eXecution Engine (AXE) - Real-time execution layer for dynamic targeting
Signals Protocol - Real-time targeting signals for brand suitability and contextual targeting
Product Discovery - How briefs lead to targeted product recommendations
Example Briefs - Real examples of effective targeting briefs
Policy Compliance - Automated compliance checking and enforcement

​Core Principle: Targeting Through Briefs

​Why Brief-Based Targeting?

​Eliminates Targeting Conflicts

​Simplifies Implementation

​Enables Accurate Pricing

​Real-Time Decisioning with AXE

​How Publishers Include Targeting

​Geographic Targeting

​Demographic Targeting

​Contextual Targeting

​Device & Platform Targeting

​Brief Examples for Common Targeting Needs

​Geographic Targeting

​Demographic Targeting

​Contextual Targeting

​Behavioral Targeting

​Product Response Targeting Information

​When to Use Targeting Overlays

​Geographic Restrictions

​Age Restrictions (Compliance)

​Device Platform (Technical Compatibility)

​Device type (form factor)

​Language (Localization)

​Frequency Capping

​Example Geographic Overlay (RCT Testing)

​What NOT to Use Targeting Overlays For

​Available Targeting Overlay Parameters

​Exclusion Semantics

​geo_countries

​geo_countries_exclude

​geo_regions

​geo_regions_exclude

​geo_metros

​geo_metros_exclude

​geo_postal_areas

​geo_postal_areas_exclude

​axe_include_segment

​axe_exclude_segment

​audience_include

​audience_exclude

​frequency_cap

​age_restriction

​device_platform

​device_type

​device_type_exclude

​language

​keyword_targets

​negative_keywords

​store_catchments

​geo_proximity

​Benefits for Different Stakeholders

​For Buyers

​For Publishers

​For Platforms

​Real-Time Targeting Signals

​Key Differences: Signals vs Overlays

​When to Use Real-Time Signals

​Managing keywords after launch

​Implementation Requirements

​Publishers MUST:

​Buyers SHOULD:

​Best Practices

​Future Evolution

​Related Documentation

Core Principle: Targeting Through Briefs

Why Brief-Based Targeting?

Eliminates Targeting Conflicts

Simplifies Implementation

Enables Accurate Pricing

Real-Time Decisioning with AXE

How Publishers Include Targeting

Geographic Targeting

Demographic Targeting

Contextual Targeting

Device & Platform Targeting

Brief Examples for Common Targeting Needs

Geographic Targeting

Demographic Targeting

Contextual Targeting

Behavioral Targeting

Product Response Targeting Information

When to Use Targeting Overlays

Geographic Restrictions

Age Restrictions (Compliance)

Device Platform (Technical Compatibility)

Device type (form factor)

Language (Localization)

Frequency Capping

Example Geographic Overlay (RCT Testing)

What NOT to Use Targeting Overlays For

Available Targeting Overlay Parameters

Exclusion Semantics

geo_countries

geo_countries_exclude

geo_regions

geo_regions_exclude

geo_metros

geo_metros_exclude

geo_postal_areas

geo_postal_areas_exclude

axe_include_segment

axe_exclude_segment

audience_include

audience_exclude

frequency_cap

age_restriction

device_platform

device_type

device_type_exclude

language

keyword_targets

negative_keywords

store_catchments

geo_proximity

Benefits for Different Stakeholders

For Buyers

For Publishers

For Platforms

Real-Time Targeting Signals

Key Differences: Signals vs Overlays

When to Use Real-Time Signals

Managing keywords after launch

Implementation Requirements

Publishers MUST:

Buyers SHOULD:

Best Practices

Future Evolution

Related Documentation