Migrating geo targeting

AdCP 3.0 replaces implicit US-centric geo targeting with named systems that support global markets. Metro targeting values are grouped by system, and postal targeting values are grouped by country plus the country-local postal system.

What changed

v2 field	v3 field	Change type
`geo_metros` (string array)	`geo_metros` (system/values objects)	Restructured
`geo_postal_codes` (string array)	`geo_postal_areas` (country/system/values objects)	Renamed and restructured

Fields that didn’t change: geo_countries, geo_countries_exclude, geo_regions, geo_regions_exclude all remain simple string arrays using ISO codes.

Metro targeting

v2 — flat array of codes, assumed to be Nielsen DMAs:

{
  "targeting": {
    "geo_metros": ["501", "602"]
  }
}

v3 — codes grouped by system:

{
  "$schema": "https://adcontextprotocol.org/schemas/v3/core/targeting.json",
  "geo_metros": [
    { "system": "nielsen_dma", "values": ["501", "602"] }
  ]
}

Each entry specifies a system and the codes within that system. Multiple systems can coexist:

{
  "$schema": "https://adcontextprotocol.org/schemas/v3/core/targeting.json",
  "geo_metros": [
    { "system": "nielsen_dma", "values": ["501", "602"] },
    { "system": "uk_itl2", "values": ["UKC1", "UKD3"] }
  ]
}

Metro systems

System	Coverage	Example codes
`nielsen_dma`	US designated market areas	`501` (New York), `602` (Chicago)
`uk_itl1`	UK regions	`UKC` (North East), `UKD` (North West)
`uk_itl2`	UK sub-regions	`UKC1` (Tees Valley), `UKD3` (Greater Manchester)
`eurostat_nuts2`	EU statistical regions	`DE11` (Stuttgart), `FR10` (Ile-de-France)
`custom`	Publisher-defined areas	Publisher-specific codes

Registered metro systems are nielsen_dma, uk_itl1, uk_itl2, eurostat_nuts2, and custom.

Postal targeting

v2 — flat array of codes, assumed to be US ZIP codes:

{
  "targeting": {
    "geo_postal_codes": ["10001", "90210"]
  }
}

v3 — renamed to geo_postal_areas, codes grouped by country-local system:

{
  "$schema": "https://adcontextprotocol.org/schemas/v3/core/targeting.json",
  "geo_postal_areas": [
    { "country": "US", "system": "zip", "values": ["10001", "90210"] }
  ]
}

Postal systems

Country	System	Precision	Example codes
`US`	`zip`	5-digit ZIP	`10001`, `90210`
`US`	`zip_plus_four`	ZIP+4	`10001-1234`
`GB`	`outward`	Outward postcode	`SW1`, `EC2`
`GB`	`full`	Full postcode	`SW1A 1AA`
`CA`	`fsa`	Forward sortation area	`M5V`, `V6B`
`CA`	`full`	Full postal code	`M5V 2T6`
`DE`	`plz`	Postleitzahl	`10115`, `80331`
`FR`	`code_postal`	Code postal	`75001`, `13001`
`AU`	`postcode`	Postcode	`2000`, `3000`
`ZA`	`postal_code`	Normal postal code	`2196`

Use postal_code for the normal postal code string in countries without a more specific registered local system. Deprecated country-fused aliases such as us_zip remain accepted for compatibility and SDK backfill. Registered country/system pairings are defined in postal-country-system.json; the published postal-system.json enum remains additive and also contains deprecated country-fused aliases for 3.x compatibility.

Exclusion targeting

v3 adds _exclude variants for metro and postal targeting:

{
  "$schema": "https://adcontextprotocol.org/schemas/v3/core/targeting.json",
  "geo_countries": ["US"],
  "geo_metros_exclude": [
    { "system": "nielsen_dma", "values": ["501"] }
  ]
}

This targets the entire US except the New York DMA.

Discovering seller capabilities

Before sending geo targeting, buyers should verify the seller supports the requested systems. Use get_adcp_capabilities:

{
  "$schema": "https://adcontextprotocol.org/schemas/v3/protocol/get-adcp-capabilities-response.json",
  "status": "completed",
  "adcp": {
    "major_versions": [3],
    "idempotency": { "supported": true, "replay_ttl_seconds": 86400 }
  },
  "supported_protocols": ["media_buy"],
  "account": {
    "supported_billing": ["operator", "agent"]
  },
  "media_buy": {
    "execution": {
      "targeting": {
        "geo_countries": true,
        "geo_regions": true,
        "geo_metros": {
          "nielsen_dma": true
        },
        "geo_postal_areas": {
          "us_zip": true,
          "us_zip_plus_four": true,
          "US": ["zip", "zip_plus_four"],
          "ZA": ["postal_code"]
        }
      }
    }
  }
}

The geo_metros object uses boolean properties to indicate which metro systems are supported. The geo_postal_areas object is keyed by country and lists the supported country-local postal systems; during the 3.x migration, sellers SHOULD also emit equivalent deprecated aliases such as us_zip where one exists. Buyers and SDKs should normalize both shapes. If you request a system the seller doesn’t declare, expect a validation error.

Full targeting example

A v3 targeting overlay combining geo restrictions:

{
  "$schema": "https://adcontextprotocol.org/schemas/v3/core/targeting.json",
  "geo_countries": ["US", "CA"],
  "geo_regions": ["US-NY", "US-CA"],
  "geo_metros": [
    { "system": "nielsen_dma", "values": ["501", "803"] }
  ],
  "geo_postal_areas": [
    { "country": "US", "system": "zip", "values": ["10001", "10002", "90210"] }
  ]
}

Inclusion fields are combined with AND logic — delivery must match all specified constraints. Exclusion fields (_exclude variants) act as AND NOT — delivery must match inclusions and must not match any exclusion.

Migration steps

Identify geo targeting

Find all uses of geo_metros and geo_postal_codes.

Rename field

geo_postal_codes becomes geo_postal_areas.

Restructure values

Wrap metro arrays into { "system": "...", "values": [...] } objects and postal arrays into { "country": "...", "system": "...", "values": [...] } objects.

Choose systems

For US-only code, use nielsen_dma and country: "US", system: "zip". For international, add the appropriate country-local systems.

Verify capabilities

Call get_adcp_capabilities to check what systems each seller supports.

Add exclusions

If needed, use the new _exclude variants for negative targeting.

Targeting

Full targeting reference: audiences, contextual, geographic, and device targeting.

​Migrating geo targeting

​What changed

​Metro targeting

​Metro systems

​Postal targeting

​Postal systems

​Exclusion targeting

​Discovering seller capabilities

​Full targeting example

​Migration steps