Targeting

Target by country, city, region, ZIP, metro, age, gender, interests and behaviours with flat fields on POST /v1/ads/create. Cities, regions and interests are opaque Meta ids: resolve them with GET /v1/ads/targeting/search first. POST /v1/ads/boost, POST /v1/ads/messaging and reach estimates take the same fields inside a targeting object.

Targeting fields

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. Do not combine cities with the countries that contain them: Meta returns a "locations overlap" error because the city is already inside the country. Drop the country, or scope countries to a different one.

Look up city and region keys

Call GET /v1/ads/targeting/search with accountId, q, dimension=geo and geoType, then 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, income, and the Meta-only workPosition, workEmployer and workIndustry.

Estimate reach

POST /v1/ads/targeting/reach-estimate with accountId, adAccountId and a spec (the same fields as above, nested) returns Meta's delivery_estimate as { available, lower, upper, estimateReady } before you create anything. estimateReady: false means Meta is still computing it; retry shortly.

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.