Targeting

Target with flat fields on POST /v1/ads/create: country, city, region, ZIP, metro, age, gender, income, interests, behaviours and custom audiences. You can also exclude locations and audiences.

Cities, regions and interests are opaque Meta ids. Resolve them with GET /v1/ads/targeting/search first.

Targeting fields

POST /v1/ads/messaging and POST /v1/ads/call take the same flat fields (and rawTargeting). POST /v1/ads/boost and reach estimates take them inside a targeting object.

On POST /v1/ads/create these sit at the top level. On POST /v1/ads/boost they live inside targeting, and cities there spell the unit distanceUnit.

Drop the country, or scope countries to a different one.

Portable fields (countries, ageMin/ageMax, gender, incomeTier, languages) carry across platforms unchanged. Every other field is meaningful only for the platform it was built against.

A field a platform cannot honour is rejected at create time with INVALID_FIELD_VALUE naming it, not silently dropped.

Look up city and region keys

Call GET /v1/ads/targeting/search with accountId, q, dimension=geo and geoType. Pass the returned id as key.

countryCode disambiguates names that exist in several countries.

The older GET /v1/ads/interests is a deprecated alias of the interest search.

import Zernio from '@zernio/node';

const zernio = new Zernio();

const { data: search } = await zernio.adtargeting.searchAdTargeting({
  query: {
    accountId: '66b2e19d8c3f5a7e9d0b1c2d',
    q: 'Amsterdam',
    dimension: 'geo',
    geoType: 'city',
    countryCode: 'NL'
  }
});

const cityKey = search.results[0].id;

Response (200):

{
  "results": [
    {
      "id": "2759794",
      "name": "Amsterdam",
      "type": "city",
      "path": ["Netherlands", "North Holland", "Amsterdam"],
      "audienceSize": null
    }
  ]
}

Then use the key on the create request, replacing countries.

EU targeting also needs the DSA beneficiary and payer, unless the ad account has defaults set:

{
  "budgetType": "lifetime",
  "endDate": "2027-03-31T23:59:00Z",
  "cities": [{ "key": "2759794", "radius": 25, "distance_unit": "kilometer" }],
  "dsaBeneficiary": "Acme BV",
  "dsaPayor": "Acme BV"
}

geoType accepts all, country, region, city (the default), subcity, neighborhood, place, zip, metro_area and geo_market.

dimension also resolves:

• interest, behavior and income
• the Meta-only workPosition, workEmployer and workIndustry
• language, which reads Google's language table and returns nothing on Meta

Estimate reach

POST /v1/ads/targeting/reach-estimate returns Meta's delivery_estimate before you create anything.

accountId, adAccountId and spec are all required. spec carries the fields above, nested.

const { data: estimate } = await zernio.adtargeting.estimateAdReach({
  body: {
    accountId: '66b2e19d8c3f5a7e9d0b1c2d',
    adAccountId: 'act_1234567890',
    spec: {
      countries: ['NL'],
      ageMin: 25,
      ageMax: 54,
      interests: [{ id: '6003107902433', name: 'Interior design' }]
    }
  }
});

Response (200), trimmed:

{
  "available": true,
  "lower": 412000,
  "upper": 585000,
  "estimateReady": true
}

estimateReady: false means Meta is still computing the estimate, which happens on a brand-new audience. Retry shortly.

An empty spec estimates the platform's broadest audience.

optimizationGoal (Meta's own vocabulary, such as REACH or LINK_CLICKS) narrows the estimate to the goal the ad set will use.

If it fails

A 400 with type: "platform_error" on create is Meta rejecting the geo combination:

{
  "error": "Invalid parameter: Your cities and countries overlap",
  "type": "platform_error",
  "platform": "meta",
  "platformError": { "code": 100 }
}

Remove the country that already contains the city.

A 404 on the search means the account's platform does not support the requested dimension.

Related

• Campaigns: the create request these fields go on.
• Audiences: customer lists, lookalikes and saved targeting.
• Reference: the placements values and special ad categories.
• Search targeting options and Estimate audience reach: every parameter.