Geo targeting defines where a campaign should run - the locations it aims to reach. A campaign can target states, cities, DMAs, or zip codes (one type at a time), and lookup helpers make it easy to find the exact locations as you build out targeting.
API operations
Relationships
Geo is configured as a top-level property on a campaign during create and update. A dedicated sub-resource endpoint also reads and writes geo for an existing campaign.
dayparting
Dayparting in settings controls WHEN ads deliver and is independent of geo.
frequencyCaps
Frequency caps in settings control HOW OFTEN a user sees ads and are independent of geo.
Key concepts
Single Tier Rule
A campaign can only target one location type at a time. States and cities cannot be combined within one campaign.
Tier Priority
When multiple tiers are provided, the API resolves to the highest-order tier: states > cities > dmas > zips.
Replace On Update
Updating geo replaces the existing geo configuration entirely.
Location Types
state targets entire US states by two-letter code; city targets cities by { name, stateCode }; dma targets Designated Market Areas by numeric id; zip targets postal codes by { code }.
Lookups
Discover available targeting values via the Geos lookup endpoints (search states, cities, DMAs, and zip codes). See the Geos entity page for those operations.
Constraints
⚠Rules to follow
Geo uses exactly one location tier per campaign.
Geo cannot be set in the campaign create payload - create the campaign first, then PUT the geo sub-resource.
Single-tier rule
Submit exactly one of states, cities, dmas, or zips per campaign. If multiple tiers are present, the API resolves to the highest-priority tier in the order states > cities > dmas > zips.
Lookup to submission mapping
States and zips use the code field. DMAs use the id field. Cities submit the full { name, stateCode } object returned by the lookup. Discover values via the Geos lookup endpoints.
Combining with audience and settings
Geo, audience segments, dayparting, and frequency caps compose as restrictions: an ad serves only when every configured dimension matches.
Response envelope
Every response is wrapped in the standard envelope { response: <payload>, timestamp: ISO-8601 timestamp, errors: [] }. The documented fields describe the contents of the response payload.
When building apps
*Targeting Tradeoffs
Tighter targeting reduces eligible impressions. If a campaign under-spends, consider relaxing one or more dimensions.