Targeting

Targeting in Semicola lives in three places:

Where	What it does
Targeting intent (campaign)	Records what the campaign intends to reach. Stored and returned on the campaign; not enforced at delivery.
Campaign constraints (campaign)	Countries and DMAs that flow into every package’s targeting overlay sent to sellers.
Package targeting overlay	The AdCP targeting a seller receives for one package. Change it on a live buy with `update_media_buy`.

Targeting intent on save_campaign

Pass targeting to save_campaign with one or more of geo, language, device, dayparts and demographics. Each dimension is a list of requirements:

{
  "targeting": {
    "geo": [{ "requirementId": "geo-us-only", "strength": "required", "include": ["US"] }],
    "device": [{ "requirementId": "ctv-preferred", "strength": "preferred", "include": ["ctv"] }],
    "language": [{ "requirementId": "en-only", "strength": "required", "include": ["en"] }]
  }
}

Field	Notes
`requirementId`	Your stable id for the requirement. It must be unique across all dimensions.
`strength`	`required` (must satisfy) or `preferred` (optimize toward).
`include`	Values to target (at least one when present).
`exclude`	Values to exclude (optional).

Dimension	Values
`geo`	ISO 3166 country codes (`US`) or region codes (`US-CA`).
`language`	BCP 47 tags (`en`, `fr-CA`).
`device`	`desktop`, `mobile`, `tablet`, `ctv`, `dooh`, `unknown`.
`dayparts`	A `timezone` (IANA, for example `America/New_York`) and `windows` of `days` (`mon`…`sun`), `startHour` (0–23) and `endHour` (1–24).
`demographics`	`age`: requirements with `minAge`, `maxAge`, `includeUnknownAge` and `allowModeledAge` (both default `false`).

The intent comes back as targeting on the campaign workspace. A save_campaign update that passes targeting replaces the whole stored intent: each call is the full desired state, not a patch.

Targeting intent is stored and returned but isn’t enforced at delivery. What sellers receive is the package targeting overlay below.

Campaign constraints

save_campaign also accepts the simpler constraint form:

{ "targeting": { "countries": ["US"], "geoMetros": ["803"], "ageRange": { "min": 25, "max": 54 } } }

countries and geoMetros flow into every package’s overlay when a media buy is sent: include lists intersect with the package’s own, exclude lists add together. If the two include lists contradict each other, the campaign’s list wins rather than widening to “anywhere”. ageRange and audience go into the brief text sellers read during discovery; channels becomes a channel filter on product discovery.

Package targeting overlays

Change a package’s targeting on a draft or live buy with update_media_buy (PATCH /api/v2/buyer/media-buys/{id}):

{
  "mediaBuyId": "…",
  "packages": [
    {
      "packageId": "…",
      "targetingOverlay": {
        "geo_countries": ["US"],
        "geo_metros": [{ "system": "nielsen_dma", "values": ["803", "501"] }],
        "device_type": ["ctv"]
      }
    }
  ],
  "reason": "Focus the flight on two markets"
}

The typed overlay fields are geo_countries, geo_regions, geo_metros, audience_include, device_type, language and the _exclude variants. Every other AdCP overlay field passes through and is validated against the AdCP schema on save.

Per-key merge. Keys you name replace the package’s current values; an empty list clears that key. Keys you omit stay as they are. Omitting targetingOverlay leaves targeting alone.
Seller support is checked first. If the seller declared which targeting it supports and your overlay uses a dimension outside that list, the update is refused with CAPABILITY_NOT_SUPPORTED before anything is sent: “Sales agent does not support the requested targeting: … Remove these targeting fields or use a sales agent that declares support.” Product discovery returns each product’s declared list as supported_targeting.
Some sellers must approve. The result may carry an update proposal.

Nielsen DMAs

DMA targeting uses geo_metros with system: "nielsen_dma" and three-digit codes such as "803".

Nielsen DMA market names aren’t available yet (they’re licensed data). Codes are accepted and saved as unverified, and the result’s warnings say so. Names can’t be matched until the dictionary lands, so send codes.

The dictionary tools are there for when names arrive; today they return an empty list with a note:

MCP tool	REST (under `/api/v2/buyer`)
`list_targeting_dimensions`	`GET /targeting/dimensions`
`list_targeting_dimension_values`	`GET /targeting/dimensions/{system}`
`resolve_targeting_dimension`	`GET /targeting/dimensions/{system}/resolve?q=…`
`list_geo_metros`	`GET /targeting/geo-metros`

nielsen_dma is the only system. When names are available, a name that could mean more than one DMA is refused with the matching codes to choose from.

Age ranges in briefs

Write one exact, closed age range in the brief (“adults ages 25–54”). Semicola’s hosted storefronts copy the numbers from the brief. If none of the proposed products can deliver that exact range, the proposal carries a limitations entry for targeting.age with the closest supported range, and says the age targeting was not applied. It never widens or approximates the range silently. Per-platform exact-age rules for the ad platforms (Meta, Google Ads, TikTok and others) aren’t available: those sellers are sandbox storefronts with no live connection yet.

Start here

Setup

Buy media

Sell media

Guides

Help

Targeting intent on save_campaign

Campaign constraints

Package targeting overlays

Nielsen DMAs

Age ranges in briefs

​Targeting intent on save_campaign

​Campaign constraints

​Package targeting overlays

​Nielsen DMAs

​Age ranges in briefs

​Related

Targeting intent on save_campaign

Campaign constraints

Package targeting overlays

Nielsen DMAs

Age ranges in briefs

Related