Skip to main content

​
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 fieldv3 fieldChange 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/3.1.0-rc.11/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/3.1.0-rc.11/core/targeting.json",
  "geo_metros": [
    { "system": "nielsen_dma", "values": ["501", "602"] },
    { "system": "uk_itl2", "values": ["UKC1", "UKD3"] }
  ]
}

​
Metro systems

SystemCoverageExample codes
nielsen_dmaUS designated market areas501 (New York), 602 (Chicago)
uk_itl1UK regionsUKC (North East), UKD (North West)
uk_itl2UK sub-regionsUKC1 (Tees Valley), UKD3 (Greater Manchester)
eurostat_nuts2EU statistical regionsDE11 (Stuttgart), FR10 (Ile-de-France)
customPublisher-defined areasPublisher-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/3.1.0-rc.11/core/targeting.json",
  "geo_postal_areas": [
    { "country": "US", "system": "zip", "values": ["10001", "90210"] }
  ]
}

​
Postal systems

CountrySystemPrecisionExample codes
USzip5-digit ZIP10001, 90210
USzip_plus_fourZIP+410001-1234
GBoutwardOutward postcodeSW1, EC2
GBfullFull postcodeSW1A 1AA
CAfsaForward sortation areaM5V, V6B
CAfullFull postal codeM5V 2T6
DEplzPostleitzahl10115, 80331
FRcode_postalCode postal75001, 13001
AUpostcodePostcode2000, 3000
ZApostal_codeNormal postal code2196
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/3.1.0-rc.11/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/3.1.0-rc.11/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/3.1.0-rc.11/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

1

Identify geo targeting

Find all uses of geo_metros and geo_postal_codes.
2

Rename field

geo_postal_codes becomes geo_postal_areas.
3

Restructure values

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

Choose systems

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

Verify capabilities

Call get_adcp_capabilities to check what systems each seller supports.
6

Add exclusions

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

Targeting

Full targeting reference: audiences, contextual, geographic, and device targeting.
Related: Channels | Pricing | Creatives | Catalogs | Attribution | AdCP 3.0 overview