Search targeting options

Resolve a human-readable query into the platform's opaque targeting ids used in the TargetingSpec (countries/regions/cities/zips/metros geo keys, and interests/behaviors entity ids) on POST /v1/ads/create, POST /v1/ads/targeting/reach-estimate, and saved_targeting audiences.

The dimension param selects what is searched, geo (locations, further scoped by geoType), interest, behavior, income, language (Google-only), or the Meta-only work demographics workPosition, workEmployer and workIndustry (their ids feed TargetingSpec.workPositions/workEmployers/workIndustries). Availability of each dimension varies by platform (e.g. behaviours are Meta/TikTok only). Work industries are a fixed ~30-entry Meta catalog with no server-side query, so workIndustry matching, ranking and limit happen in Zernio. language is likewise a fixed, checked-in table of Google's targetable language_constant rows (id, ISO code, name) matched by name or code, capped at 20, with no network call; its ids feed TargetingSpec.languages. Results are normalized across platforms into a single shape, so the same client code consumes Meta, TikTok, LinkedIn, X, Pinterest, and Google results.

TikTok geo searches return every matching level in one list (type is country, region, city, district, or metro for DMA areas) — geoType is not applied. Results are scoped to the advertiser's targetable markets, and every id is usable in regions/cities/metros keys on POST /v1/ads/create.

LinkedIn geo searches also return every matching level in one list, and neither geoType nor countryCode is applied: LinkedIn's typeahead only returns a name and a URN per result, with no level or country field to filter on. Every result has type set to location, and its id is a urn:li:geo:* URN usable as a regions[].key on POST /v1/ads/create, POST /v1/ads/boost and POST /v1/ads/targeting/reach-estimate.

Google geo searches resolve against Google's geoTargetConstants and return every matching level in one list; geoType is not applied (Google's target_type is an open taxonomy that does not map one-to-one onto the geoType enum), so filter client-side on the returned type (country, region, city, zip, metro, or the lowercased Google target type for rarer levels). countryCode scopes the search to one country. Each id is Google's numeric criterion id, usable as a regions/cities/zips/metros key on POST /v1/ads/create. Google city radius is not supported (pass a customLocations lat/lng pin for a radius); country targeting also accepts plain ISO codes via countries with no search call.

Pinterest resolves against three whole-catalog endpoints (interests, locations, regions) with no server-side query or pagination, so matching, ranking and the limit cutoff all happen in Zernio; the catalog is independent of any ad account and results never carry audienceSize. Names come back localized to the connected Pinterest account's language (there is no way to force a locale), so match against whatever language that account returns. geoType routes to a different catalog: country and metro_area read the locations catalog (type is country or metro); region reads the regions catalog (type is region, its id a regions[].key on POST /v1/ads/create); all and the default city merge both catalogs with honest per-entry types, since Pinterest has no city-level catalog and city is an alias for all, not a literal city search. zip, subcity, neighborhood, place and geo_market return a 400: Pinterest exposes no postal-code catalog, pass postal codes directly as targeting.zips: [{ key }] on POST /v1/ads/create.

For geo queries, q should contain only the locality name (e.g. "Amsterdam", not "Amsterdam, NL"). Use countryCode to disambiguate.

{  "results": [    {      "id": "string",      "name": "string",      "type": "string",      "path": [        "string"      ],      "audienceSize": 0    }  ]}