Targeting

By the end of this page, a new Google campaign reaches the places, languages and people you choose, and you can change that targeting once it runs.

Before you start

You need a googleads account and the create call from Create a campaign.

Targeting fields

Send the fields in the targeting object of POST /v1/ads/create. The same names also work flat on the request body, and a flat field replaces its nested value.

Performance Max and Demand Gen accept only geo and language fields (plus excludedLocations on Performance Max). Every other field, including customLocations, incomeTier, audienceInclude, audienceExclude and top-level audienceId, returns 400. Demand Gen takes its audience in demandGen instead (Demand Gen).

Interests are create-only, and they return 400 when the request joins an existing ad group with adSetId.

import Zernio from '@zernio/node';

const zernio = new Zernio();

const { data: created } = await zernio.adcampaigns.createStandaloneAd({
  body: {
    accountId: '66b2e19d8c3f5a7e9d0b1c2d',
    adAccountId: '1234567890',
    name: 'US DevOps Search',
    campaignType: 'search',
    goal: 'traffic',
    budgetAmount: 50,
    budgetType: 'daily',
    headline: 'Internal Developer Platforms',
    body: 'Spec-driven platform engineering.',
    linkUrl: 'https://example.com/platform',
    keywords: ['internal developer platform'],
    locationTargetingType: 'presence',
    targeting: {
      countries: ['US'],
      excludedLocations: { countries: ['CA'] },
      languages: ['en'],
      ageMin: 25,
      ageMax: 54
    }
  }
});

Response (201), the same shape as any create:

{
  "ad": {
    "_id": "66f0a1b2c3d4e5f6a7b8c9d0",
    "name": "US DevOps Search",
    "platform": "google",
    "status": "pending_review",
    "adType": "standalone",
    "goal": "traffic",
    "budget": { "amount": 50, "type": "daily" },
    "platformAdId": "735198246013",
    "platformCampaignId": "21874563210",
    "platformAdSetId": "165489732105"
  },
  "message": "Ad created"
}

Look up Google ids

Call GET /v1/ads/targeting/search with accountId, q and dimension. On Google, dimension takes geo, interest, language and income.

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

const cities = search.results.filter((result) => result.type === 'city');

Response (200):

{
  "results": [
    { "id": "1026201", "name": "Austin", "type": "city", "path": ["Texas", "United States"] }
  ]
}

A geo search returns every matching level in one list, because Google ignores geoType. Filter on each result's type (country, region, city, zip, metro). countryCode scopes the search to one country.

A country result's id is its ISO code, for countries. Every other id is Google's numeric id, for the key of regions, cities, zips or metros.

• interest returns Google's affinity and in-market segments. Google has no separate behavior catalog.
• language reads Google's language table without calling Google. It returns 20 results by default, and limit (up to 100) overrides that.
• income returns the one tier Google targets, top_10.

Location targeting type

locationTargetingType is a top-level field that sets who a new campaign's locations reach:

Excluded locations always use presence.

It is set on the new campaign only. A request that joins an existing campaign (existingCampaignId or adSetId) returns 400. It is Google-only and returns 400 on other platforms.

Change a running campaign

PUT /v1/ads/campaigns/{campaignId}/targeting changes a Google campaign's devices, locations, excludedLocations, languages and locationTargetingType. campaignId is Google's numeric campaign id.

const { data: retargeted } = await zernio.adcampaigns.updateCampaignTargeting({
  path: { campaignId: '21874563210' },
  body: {
    platform: 'google',
    targeting: {
      locations: { countries: ['US'], cities: ['1026201'] },
      languages: ['en', 'es'],
      locationTargetingType: 'presence'
    }
  }
});

Response (200), trimmed:

{
  "campaignId": "21874563210",
  "updated": ["locations", "languages", "locationTargetingType"],
  "locationTargetingType": "presence",
  "locations": [
    { "geoTargetId": "2840", "negative": false, "name": "United States", "type": "Country", "countryCode": "US" },
    { "geoTargetId": "1026201", "negative": false, "name": "Austin", "type": "City", "countryCode": "US" }
  ],
  "languages": [
    { "code": "en", "id": "1000", "name": "English" },
    { "code": "es", "id": "1003", "name": "Spanish" }
  ]
}

Each field you send replaces that whole set on the campaign. A field you leave out stays as it is.

• locations takes a bare array of ISO codes, or countries, regions, cities, zips and metros lists. It leaves excluded locations alone.
• excludedLocations takes the same shapes. An empty list removes every exclusion.
• devices is the full set of MOBILE, DESKTOP, TABLET and CONNECTED_TV, with an optional bidModifier each. A device you leave out is switched off with a bid modifier of 0, because Google cannot remove a device.

Locations, languages and devices are campaign-level on Google, so the change applies to every ad group and ad in the campaign. Each set's removes and creates go out in one Google request. locationTargetingType, devices, locations, radius and languages go as separate calls, so a failure part-way leaves earlier fields applied.

GET /v1/ads/campaigns/{campaignId}/targeting reads the current set. Keyword edits are on Keywords.

Demand Gen. Google keeps a Demand Gen campaign's locations and languages on its ad group. excludedLocations returns 400. With one ad group they are written there and the response carries its adGroupId.

With several ad groups the call returns 400 naming them. Edit each one with targeting on PUT /v1/ads/{adId}, on an ad of that ad group.

If it fails

Related

• Create a campaign: the create call these fields ride on.
• Customer Match: build the user list for audienceInclude.
• Keywords: keyword targeting on Search ad groups.
• Search targeting options and Edit campaign targeting: every parameter.