> ## Documentation Index
> Fetch the complete documentation index at: https://agenticadvertisingorg-snap-format-preview-links.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Migrating geo targeting
> Migrate AdCP geo targeting from v2 to v3. Replaces implicit US-centric targeting with named systems (Nielsen DMA, postal codes) for global market support.
# 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:
```json theme={null}
{
"targeting": {
"geo_metros": ["501", "602"]
}
}
```
**v3** — codes grouped by system:
```json theme={null}
{
"$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:
```json theme={null}
{
"$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:
```json theme={null}
{
"targeting": {
"geo_postal_codes": ["10001", "90210"]
}
}
```
**v3** — renamed to `geo_postal_areas`, codes grouped by country-local system:
```json theme={null}
{
"$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:
```json theme={null}
{
"$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`:
```json theme={null}
{
"$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:
```json theme={null}
{
"$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
Find all uses of `geo_metros` and `geo_postal_codes`.
`geo_postal_codes` becomes `geo_postal_areas`.
Wrap metro arrays into `{ "system": "...", "values": [...] }` objects and postal arrays into `{ "country": "...", "system": "...", "values": [...] }` objects.
For US-only code, use `nielsen_dma` and `country: "US", system: "zip"`. For international, add the appropriate country-local systems.
Call `get_adcp_capabilities` to check what systems each seller supports.
If needed, use the new `_exclude` variants for negative targeting.
Full targeting reference: audiences, contextual, geographic, and device targeting.
***
**Related:** [Channels](/docs/reference/migration/channels) | [Pricing](/docs/reference/migration/pricing) | [Creatives](/docs/reference/migration/creatives) | [Catalogs](/docs/reference/migration/catalogs) | [Attribution](/docs/reference/migration/attribution) | [AdCP 3.0 overview](/docs/reference/whats-new-in-v3)