Targeting

AdCP targeting — how natural language briefs replace taxonomy-based audience selection, with geographic overlays and real-time decisioning at impression time.

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 TMP

For targeting decisions that must happen at impression time, AdCP uses the Trusted Match Protocol (TMP). TMP is the real-time execution layer that evaluates pre-negotiated packages at serve time across any surface.

TMP gives the buyer a real-time look at each eligible impression through two structurally separated operations — Context Match (content relevance) and Identity Match (user eligibility) — without exposing user identity and page context to the buyer simultaneously.

Key capabilities:

• Cross-publisher frequency capping: Manage user exposure across multiple publishers via the Identity Match path
• Dynamic audience targeting: Evaluate audience membership at impression time without sharing PII
• Brand suitability enforcement: Real-time content evaluation through the Context Match path
• First-party data activation: Use your customer data without exposing it to publishers

When to use TMP:

• Cross-publisher frequency caps
• Suppression lists (existing customers, past converters)
• Audience segments that can’t be expressed in a brief
• Real-time brand suitability beyond static rules
• Any impression-time decision across web, mobile, CTV, AI assistants, or retail media

See the TMP documentation for the full specification and surface-specific integration guides.

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
  }
}

Product Filters vs Targeting Overlays

Some targeting dimensions appear in both get_products filters and create_media_buy targeting overlays. These serve different purposes at different stages:

Filter (get_products)	Overlay (create_media_buy)	Filter: what it does	Overlay: what it does
countries	geo_countries / _exclude	Show products serving these countries	Deliver only in these countries
regions	geo_regions / _exclude	Show products serving these regions	Deliver only in these regions
metros	geo_metros / _exclude	Show products serving these metros	Deliver only in these metros
postal_areas	geo_postal_areas / _exclude	Show products serving these postal codes	Deliver only in these postal codes
geo_proximity	geo_proximity	Show products with inventory near this point	Deliver only to users near this point
keywords	keyword_targets / negative_keywords	Show products supporting these search terms	Bid on these specific terms

Filters tell the sell-side agent what matters to the buyer so it can curate relevant products. Without a proximity filter, a seller might recommend products that don’t support geo_proximity — and the buyer wouldn’t discover the gap until create_media_buy.

Overlays apply the precise functional constraint at execution time. The overlay is what the seller’s ad server enforces.

Value filters (countries, regions, metros, postal_areas, geo_proximity, keywords) narrow by coverage area — “show me inventory in these places.” Capability filters (required_geo_targeting, required_features) narrow by what the seller can enforce — “only sellers that support zip-level targeting.” These compose: use both when you need inventory in a specific area from sellers that can target at that granularity.

For buyers: pass filters at discovery time, then apply the same values (or refined versions) as overlays at buy time. Note that overlay schemas are stricter — for example, keyword_targets requires match_type while the keywords filter defaults to broad.

Example: discovery to buy

// Step 1: get_products — signal intent with filters
{
  "brief": "Coffee shop promotion in downtown Seattle",
  "filters": {
    "geo_proximity": [{
      "lat": 47.6062,
      "lng": -122.3321,
      "label": "Downtown Seattle",
      "radius": { "value": 5, "unit": "mi" }
    }],
    "keywords": [{ "keyword": "coffee" }]
  }
}

// Step 2: create_media_buy — apply precise constraints as overlays
{
  "targeting": {
    "geo_proximity": [{
      "lat": 47.6062,
      "lng": -122.3321,
      "label": "Downtown Seattle",
      "radius": { "value": 5, "unit": "mi" }
    }],
    "keyword_targets": [{ "keyword": "coffee", "match_type": "broad" }]
  }
}

Note that keywords (filter) becomes keyword_targets (overlay), and match_type becomes required.

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/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/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/core/targeting.json",
  "device_type": ["mobile", "tablet"]
}

Exclusion — use device_type_exclude to exclude specific form factors:

{
  "$schema": "/schemas/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/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/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/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": [
    {
      "product_id": "national_video",
      "targeting_overlay": {
        "geo_countries": ["US"],
        "geo_metros_exclude": [
          { "system": "nielsen_dma", "values": ["501", "803", "602"] }
        ]
      }
    },
    {
      "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": [
    {
      "product_id": "national_video",
      "targeting_overlay": {
        "geo_metros": [
          { "system": "nielsen_dma", "values": ["501", "602", "803"] }
        ]
      }
    },
    {
      "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: Segment ID for inclusion targeting (legacy AXE field)
• Format: String segment identifier
• Examples: "seg_auto_intenders_q1", "audience_lapsed_buyers_30d"
• Use cases: Dynamic audience targeting, first-party data activation
• Note: This field is from the legacy AXE integration. New implementations should use TMP, where audience targeting is handled through the Identity Match path.

axe_exclude_segment

• Description: Segment ID for exclusion targeting (legacy AXE field)
• Format: String segment identifier
• Examples: "seg_existing_customers", "audience_past_converters"
• Use cases: Customer suppression, frequency management
• Note: This field is from the legacy AXE integration. New implementations should use TMP, where suppression is handled through the Identity Match path.

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/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/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/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/core/targeting.json",
  "geo_proximity": [
    {
      "lat": 51.4700,
      "lng": -0.4543,
      "label": "Heathrow Airport",
      "radius": { "value": 30, "unit": "km" }
    }
  ]
}

{
  "$schema": "/schemas/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:

1. 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
2. Interpret Briefs: Use briefs to determine appropriate audience and content targeting
3. Validate Targeting: Reject media buys with targeting that cannot be supported
4. Document Limitations: Clearly communicate any geographic targeting limitations in product descriptions

Buyers SHOULD:

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

Best Practices

1. Default to briefs - Start with natural language descriptions
2. Write Clear Briefs: Be specific about audience and context requirements
3. Trust Publisher Expertise: Publishers know their inventory capabilities best
4. Use signals for dynamic targeting - Real-time signals handle complex, high-cardinality targeting better than overlays
5. Minimize Technical Overlays: Use only for geographic restrictions or compliance
6. Validate Audience Fit: Ensure product descriptions match campaign goals
7. 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

Related Documentation

• Trusted Match Protocol (TMP) - Real-time execution layer for impression-time targeting, frequency capping, and brand suitability
• 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