(Translated by https://www.hiragana.jp/)
Google Ads Developer Blog: targeting

Starting June 23, 2022, attempting to create a CampaignSharedSet with a shared_set that has a status of REMOVED will cause a MutateError.RESOURCE_NOT_FOUND error in the Google Ads API.

There will also be a one-time change to automatically update CampaignSharedSet entities to a status of REMOVED if they contain a shared_set with a status of REMOVED. Because the shared_set already has a REMOVED status, this won’t impact any active campaigns since we’re only changing CampaignSharedSet entities that don’t currently serve.

Starting June 23, 2022, attempting to create a CampaignSharedSet with a shared_set that has a status of REMOVED will cause a MutateError.RESOURCE_NOT_FOUND error in the Google Ads API.

There will also be a one-time change to automatically update CampaignSharedSet entities to a status of REMOVED if they contain a shared_set with a status of REMOVED. Because the shared_set already has a REMOVED status, this won’t impact any active campaigns since we’re only changing CampaignSharedSet entities that don’t currently serve.

Where can I get support?

If you have questions, please reach out to us on the forum or at googleadsapi-support@google.com.

On , the maximum number of user_identifers set in a UserData object will be reduced from 100,000 to 20. This is to clarify that each set should represent a single user.
On January 10, 2022, the maximum number of user_identifers set in a UserData object will be reduced from 100,000 to 20. This is to clarify that each set should represent a single user.

The table below illustrates uploading UserData for two users (John Doe and Max Mustermann), each of whom has two email addresses.




Correct usage
operations: {
  create: {
    user_identifiers {
      hashed_email: hash(“johndoe@gmail.com”)
    },
    user_identifiers {
       hashed_email: hash(“johndoe@google.com”)
    } 
  }
}
operations: {
  create: {
    user_identifiers {
      hashed_email: hash(“maxmustermann@gmail.com”)
    },
    user_identifiers {
      hashed_email: hash(“maxmustermann@google.com”)
    }
  }
}
Incorrect usage
operations: {
  create: {
    user_identifiers { 
      hashed_email:  hash(“johndoe@gmail.com”) 
    },
    user_identifiers {
      hashed_email:  hash(“johndoe@google.com”)
    },
    user_identifiers { 
      hashed_email: hash(“maxmustermann@gmail.com”)
    },
    user_identifiers { 
      hashed_email: hash(“maxmustermann@google.com”)
    }
  }
}

UserData is used for Customer Match and store sales uploads. In a given create/remove UserData operation, each set of user_identifiers should be for a single user.

Note that the same total amount of data can be sent in a single request, but each set of user_identifiers must represent a single person.

If the number of user_identifiers for a single set exceeds the new limit of 20, a TOO_MANY_USER_IDENTIFIERS error will be generated.

This will be applied to the two Google Ads API methods that provide UserData uploads:

If you have any questions or need additional help, contact us via the forum.

Starting January 2021, over 1500 deprecated Geo Region targeting options will no longer be supported in Display & Video 360. This announcement, along with the full list of deprecated options, can be found on the Geography Targeting Help Center article. These deprecated targeting options reflect outdated geographical regions and, therefore, do not change the serving of line items.

How will this happen in the API?

This sunset will be reflected in the Display & Video 360 API through the following sequence of events:
  1. Starting today, we will begin removing deprecated targeting from older resources. These resources consist of Line Items or Insertion Orders that are currently archived or have been paused for more than six months.
  2. In February 2021, the deprecated targeting options will no longer be retrievable through the Targeting Options service and attempts at assigning or removing deprecated targeting through the Line Item Assigned Targeting Options service will return an error.
  3. After the deprecated targeting options are no longer able to be assigned, we will begin removing deprecated targeting from all remaining resources. Any line items only using deprecated targeting will be paused upon the removal of said targeting. This concludes the formal sunset of the deprecated targeting options.

What should I do to prepare for this?

In anticipation of this sunset, it is recommended that you do the following:

  1. Check to see if any existing Line Items utilize deprecated targeting options. Use advertisers.lineItems.targetingTypes.assignedTargetingOptions.list to list the assigned Geo Region targeting for each active line item and check the targeting against the deprecated targeting options. Remove or replace any deprecated targeting as soon as possible using advertisers.lineItems.bulkEditLineItemAssignedTargetingOptions.
  2. If you are storing oft-used targeting option IDs locally, cross-reference them against the list of deprecated targeting options. This will avoid errors caused by attempting to assign sunset targeting options.

Should I expect more deprecations in the future?

Users should expect the occasional deprecation and sunset of targeting options in Display & Video 360 in much smaller quantities than this deprecation. As such, future deprecations likely won’t be announced through a blog post or documentation change.

In order to account for these deprecations, it is recommended that you use targetingTypes.targetingOptions.get to confirm that a targeting option is still available before assigning it. This should be done before assigning any option not obtained through the Targeting Options service, including those stored locally or copied from existing targeting. This will avoid errors caused by attempting to assign deprecated targeting.

You can read more about the Targeting Options and Assigned Targeting Options services in our reference documentation and on the Set Targeting page of our Managing Line Items guide.
If you have questions or run into issues navigating this process, please contact us using our support contact form.

What's changing
Starting September 18, 2018, AdWords API requests that attempt to target or exclude a Placement criterion where the url is exactly adsenseformobileapps.com will fail and result in a CriterionError with reason INVALID_PLACEMENT_URL. You can read more about this change in the Google Ads help center.

What you should do
Modify your application so that it does not add the above Placement criterion via the AdWords API, and review and modify your mobile targeting to achieve your campaign goals. You will no longer be able to exclude all mobile apps from targeting using this Placement criterion, but you can refine your mobile app targeting and exclusions using any of the following criteria: For more details, check out the criteria usage grid that indicates which criterion types can be targeted and excluded at the campaign or ad group level. If you have any questions or need help, please contact us via the forum.

We are rolling out a change to the way placements work when specifying YouTube URLs. Starting on August 14, 2018, using generic placements to specify YouTube channels or videos is going to be disallowed and will result in an error.

For more accurate video targeting, even when videos are played across platforms, use the new specific YouTubeChannel and YouTubeVideo placement criteria when you want to target specific channels or videos in AdWords scripts.

If you have any questions about these changes or AdWords scripts in general, you can post them on our developer forum.

What's changing
Historically, some types of audiences have only been available for targeting and bidding in Display campaigns, as indicated by UserList.isEligibleForSearch = false in the AdWords API.

Starting at the end of September, 2016, both AdWords and the AdWords API will allow you to target additional audiences in Search and Shopping campaigns.

What you should do
  • Make sure that your application does not make assumptions about which user lists are available for Search and Shopping campaigns. Instead, your application should check the value of the isEligibleForSearch attribute of each UserList.
  • You can discover the audiences in your AdWords account and their eligibility for Search, Shopping, or Display campaigns by issuing an AdwordsUserListService get or query request that includes the IsEligibleForSearch and IsEligibleForDisplay selector fields. On an ongoing basis, you should periodically check for user lists where eligibility has changed due to improvements in AdWords.
  • If you'd like to add additional audience targeting to your Search or Shopping ad groups, add a BiddableAdGroupCriterion with a criterion set to an instance of the appropriate type of UserList. Make sure that your application can handle an OperationAccessDenied.OPERATION_NOT_PERMITTED_FOR_CAMPAIGN_TYPE error, which will occur if the particular UserList in your request is not currently available for Search and Shopping campaigns.
Further reading
For an overview of remarketing and audience targeting in the AdWords API, check out the Remarketing and audience targeting guide.

If you have any questions, please post on the forum or the Ads Developers Plus Page.

Adwords currently supports demographic targeting only for Display network campaigns, but starting September 19, 2016 and launching over the subsequent days, demographic targeting will also be supported for Search campaigns. All existing AdWords API versions will retroactively allow these criteria in Search campaigns.

The benefit here for AdWords API users is that AgeRange and Gender criteria will be allowed in Search campaigns. Formerly, you would receive a CriterionError.CANNOT_ADD_CRITERION_TO_SEARCH_PLUS_CAMPAIGNS error when trying to add these types.

If your application does any type of automatic bidding, make sure that you update your app to accommodate these new potential bid modifiers on Search campaigns before September 19. These new criteria may be added by users of the AdWords user interface, so your code may have to handle them even if your application doesn't add them explicitly. This may be particularly relevant if you use the "Target and bid" (targetAll=false) option in TargetingSettingDetail, because the new criteria will begin restricting targeting.

If you have any questions about this change, or other questions about the AdWords API, contact us via the forum.

In December 2014, we announced that “Other interests” has been superseded by affinity and in-market audiences. As a part of this transition, the associated criteria are no longer supported in AdWords API v201502.

To finalize this sunset, we’ll be auto-upgrading existing deprecated criteria of this type to supported ones. The auto-upgrade will happen gradually over several weeks starting May 15, 2015.

Campaigns that target "Other interests" will be automatically upgraded to one or more of the following options:
  • Affinity audiences for driving brand awareness and engagement from a defined list of categories;
  • In-market audiences for reaching customers actively researching and intending to make a purchase;
  • Topic targeting to target websites about specific topics.
Campaigns with "Other interests" exclusions will be converted to Topic exclusions during this upgrade. Campaigns that don’t target "Other interests" will not be affected by this upgrade. If you'd like to keep full control of your campaign targeting, make sure to upgrade your campaigns before May 15.

If you have any questions or need help with the upgrade, please post on the forum or the Ads Developers Plus Page.

A lot of our DFP API developers have been asking recently about how to filter report data by custom targeting key ID. Currently the DFP API allows you to filter report data by custom targeting value ID only. Until we have official support for filtering by custom targeting key ID in reports, you can use the CustomTargetingService and the ReportService together to achieve this goal.

A lot of our DFP API developers have been asking recently about how to filter report data by custom targeting key ID. Currently the DFP API allows you to filter report data by custom targeting value ID only. Until we have official support for filtering by custom targeting key ID in reports, you can use the CustomTargetingService and the ReportService together to achieve this goal.

Step 1: Use CustomTargetingService to get your keys and values

You will first need to use getCustomTargetingValuesByStatement and filter by the custom targeting keys you’re interested in to obtain all the corresponding values. For example:

    WHERE customTargetingKeyId IN (17, 18, 19)

If you have a lot of keys and values in your network, a better approach is to store these in a local database and do nightly syncs. Use getCustomTargetingKeysByStatement to obtain all the keys in your network, and then iterate through them, calling getCustomTargetingValuesByStatement for each key to obtain their values. Our client libraries all have examples of this. For instance, the Java example can be found in our ads Java client library GitHub repository. This way, you can look up the values associated with a custom targeting key more quickly and not do an additional API call.

Step 2: Use the values in a report query

Once you have the values for the custom targeting key you’re interested in, you can then use the ReportQuery.statement with the PQL IN clause to filter on the CUSTOM_TARGETING_VALUE_ID dimension. For example, say you were interested in filtering on custom targeting key ID of 7777. You look up the values of 7777 in Step 1, which gives you three value IDs: 3211, 88990, 123456. You can then use the IDs to effectively filter your report data by custom targeting key ID 7777.

    WHERE CUSTOM_TARGETING_VALUE_ID IN (3211, 88990, 123456)

However, please be aware that if you have a lot of custom targeting value IDs to filter on, you should batch them by querying for no more than 500 IDs at a time in the PQL IN clause. For example, you will run your report filtering on the first 500 IDs you’ve collected and save that report. Then you will run the same report on the next page of 500 IDs you’ve collected and so on until you have no more IDs. You can then combine the reports locally so that you have all the data for those custom targeting IDs.

If you have any questions about this, feel free to drop us a line on the DFP API forums or Ads Developer Google+ page.

As previously announced on the AdWords blog, we're improving how exact and phrase keywords match to users' search terms. Starting in late September, all phrase and exact match keywords will begin matching close variants, including misspellings, singular/plural forms, stemmings, accents, acronyms and abbreviations.

Specifically to the API, this means the following:
  • The next API version will no longer accept KeywordMatchSetting for campaigns.
  • Existing API versions will ignore the value sent for the optIn field of KeywordMatchSetting.
  • Regardless of the optIn field value, all exact and phrase match keywords will match close variants.
Close variant matching is already enabled by default for new campaigns, so if you haven't specifically set the optIn field, you won't see any changes in keyword matching behavior.

If you have any questions, please feel free to contact us on the forum or via the Google Plus page.

Imagine for a moment that you're a mobile line item. You've just been initialized locally, and all of a sudden you’re having an existential crisis -- what makes you, you? How are you different from all the other line items? Sure your associated creative might be a bit different from other line items and you might have a few extra impressions allotted to your goal, but what truly makes you... unique? In this series of posts, we'll take you on an incredible journey through a day in the life of a mobile line item -- from how to target mobile to the actual delivery on a device.

Imagine for a moment that you're a mobile line item. You've just been initialized locally, and all of a sudden you’re having an existential crisis -- what makes you, you? How are you different from all the other line items? Sure your associated creative might be a bit different from other line items and you might have a few extra impressions allotted to your goal, but what truly makes you... unique? In this series of posts, we'll take you on an incredible journey through a day in the life of a mobile line item -- from how to target mobile to the actual delivery on a device.

Adding mobile specific targeting

It all starts similarly enough: you need a name, an order ID, start and end dates, a goal, and all the usual suspects -- but wait, there's more! Instead of just having custom criteria, ad units, and geo-targeting, you find that you also have TechnologyTargeting fields specified, like:

  • DeviceCategoryTargeting
  • OperatingSystemTargeting
  • MobileCarrierTargeting

Now, say you're being created as a line item to advertise Android tablet cases. It doesn't make much sense for you to be delivered to an iPad or an iPhone, so we need to add technology specific targeting.

To do so using Java, we would first set the DeviceCategory object with the targeting ID of the 'Tablet' category and the OperatingSystem object with the targeting ID of 'Android', both of which we'd pull from the PublisherQueryLanguage service:

    DeviceCategory deviceCategory = new DeviceCategory();
    OperatingSystem operatingSystem = new OperatingSystem();

    deviceCategory.setId(30002L);
    operatingSystem.setId(501013L);

These would then be set on the DeviceCategoryTargeting and OperatingSystemTargeting objects:

    DeviceCategoryTargeting deviceCategoryTargeting = new DeviceCategoryTargeting();
    OperatingSystemTargeting operatingSystemTargeting = new OperatingSystemTargeting();

    deviceCategoryTargeting.setTargetedDeviceCategories(new DeviceCategory[] {deviceCategory});
    operatingSystemTargeting.setOperatingSystems(new OperatingSystem[] {operatingSystem});

Finally, the Targeting object will have a TechnologyTargeting object set for DeviceCategoryTargeting and also OperatingSystemTargeting:

    TechnologyTargeting techTargeting = new TechnologyTargeting();
    technologyTargeting.setDeviceCategoryTargeting(deviceCategoryTargeting);
    technologyTargeting.setOperatingSystemTargeting(operatingSystemTargeting);

    Targeting targeting = new Targeting();
    targeting.setTechnologyTargeting(techTargeting);

Now what happens? You're a line item that has a bit of technology targeting specified, but where are you off to next? Stay tuned for what happens next in - 'A day in the life of a mobile line item, part 2.'

Starting on April 22nd, 2014, a v201309 or v201402 AdGroupBidModifierService.mutate request will fail with a CriterionError and reason CANNOT_BID_MODIFY_CRITERION_TYPE if all of the following conditions are met for the same criterion:
  • The criterion is a Platform criterion for the mobile platform ID (30001)
  • The Campaign has a CampaignCriterion for the mobile platform criterion with a bidModifier set to 0 (this is displayed as a Bid adj. of -100% under Settings in the AdWords UI)
  • The AdGroupBidModifier has the same mobile platform criterion and attempts to set the bidModifier to any value other than 0
The AdWords API and UI will start rejecting such requests because allowing this combination could give the impression that the ad group will serve ads for the mobile platform criterion when in fact it will not.

For example, assume you create a campaign with a CampaignCriterion containing the following criterion and bid modifier:
<criterion xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:type="Platform">
    <id>30001</id>
    <type>PLATFORM</type>
    <Criterion.Type>Platform</Criterion.Type>
    <platformName>HighEndMobile</platformName>
</criterion>
<!-- This will appear as "-100%" in the UI. -->
<bidModifier>0.0</bidModifier>
If you attempt to create an AdGroupBidModifier containing the following criterion and bid modifier for any ad group in the campaign on or after April 22nd, 2014, it will fail because the non-zero ad group bid modifier of 1.25 would have no effect:
<criterion xmlns:ns2="https://adwords.google.com/api/adwords/cm/v201402"
  xsi:type="ns2:Platform">
    <ns2:id>30001</ns2:id>
</criterion>
<!-- This will appear as "+125%" in the UI.  Any other non-zero
     value will also fail. -->
<bidModifier>1.25</bidModifier>
Before April 22nd, 2014, please take the following actions to ensure a smooth transition for your application:
  • Make sure that your application will be able to properly handle the error
  • Examine your existing campaigns and ad groups and address any bid modifiers that meet the conditions above
Not using bid adjustments in your campaigns and ad groups? Check out our bid modifiers guide to learn how to use this powerful feature of AdWords.

Still have questions? Feel free to visit us on the AdWords API Forum or our Google+ page.

Building on our AdWords announcement in November 2013, v201402 of the AdWords API supports geo targeting for areas with particular places of interest or income levels. These are useful for reaching customers based on the types of places they visit or demographic information based on their location. Please check the support site for more information, and to determine if these new targeting options are available for the country you would like to target. Within the API, these new criteria types are called LocationGroups and can be applied on a campaign to affect all of its ads.

The targeting can be set up using a matching function, which you may already be familiar with from other parts of the API. There are three new operand types for LocationGroups matching functions. Each matching function will pair one of either IncomeOperand or PlacesOfInterestOperand with a GeoTargetOperand, which is always required, to target income brackets or places of interest within a specific geographical region.

For example, to target airports in New York City using the Java client library, you would set up a matching function using a PlacesOfInterestOperand and a GeoTargetOperand, like this:
LocationGroups locationGroup = new LocationGroups();
Function matchingFunction = new Function();
matchingFunction.setLhsOperand(new FunctionArgumentOperand[] {
    new PlacesOfInterestOperand(null, PlacesOfInterestOperandCategory.AIRPORT)
});
matchingFunction.setOperator(FunctionOperator.AND);
matchingFunction.setRhsOperand(new FunctionArgumentOperand[] {
    new GeoTargetOperand(null, new long[]{ 1023191L }) // ID for NYC
});
locationGroup.setMatchingFunction(matchingFunction);
You can look up geo target IDs via the LocationCriterionService or in the documentation. You can also see fully functional, runnable code demonstrating this criterion type in each client library (Java, PHP, .NET, Python, Ruby, Perl).

If you have any questions about this or anything else related to the AdWords API, please contact us on the forum or via our Google+ page.

In v201311 we changed how the API returns locations to:
  • More granularity in targeting 
  • Streamlined code paths 
  • Increased flexibility for handling location objects
Along with the update to location objects, we've also expanded the list of targetable locations far beyond what was previously available. If you look at new ...
In v201311 we changed how the API returns locations to:
  • More granularity in targeting 
  • Streamlined code paths 
  • Increased flexibility for handling location objects
Along with the update to location objects, we've also expanded the list of targetable locations far beyond what was previously available. If you look at new Geo_Target table - which replaces the individual City, Country, Metro, Postal Code, and Region tables - you’ll find that you now have far more control over where your ads will serve. In the past, the smallest location you could target was a city; now, you can target something as specific as an Airport.

Many of you have asked how to migrate from the deprecated PQL tables to the new Geo_Target table.

Instead of having a table for each geo locations type, we combine everything into a single table with the type defined as a new column. This not only makes things easier for you, it also allows us to add even more types of locations to target in the future without having to make new tables.

As far as how the old tables relate to the new Geo_Target table, the Country, City, Postal_Code, and Region tables will map to their respective namesake columns, with only the Metro table being different, now mapping to the more canonical DMA_Region. To see how simple it is to replicate the old behavior, look at this Python example that pulls down the targetable City locations.

If you’re not entirely sure how to break out your targeting into smaller geo locations, we’ve got you covered there too - instead of trying to make your own relational mapping between cities, metros, regions, and countries, the new Geo_Target table simplifies the task with the ParentIds field, which yields a list of parent location IDs that encompass a child location.

For the new year, make a resolution to switch over to the new Geo_Target table and reap the benefits thereafter.

With the recent change to the Search Network setting in the AdWords API we’ve noticed a few cases where network settings were used to pause campaigns by disabling all possible networks. To simplify campaign management and reduce ambiguity, we will disallow this campaign state going forward. Any operation disabling every network for a campaign will produce TargetError.TARGET_ERROR starting Nov 12th 2013.

The change will affect only versions v201309 and later. If you use network settings to pause your campaigns and have already migrated to v201309, please use the campaign status PAUSED instead.

If you do not update campaigns with every network target set to false, this change will not affect you.

As always, please feel free to ask any questions on the AdWords API forum or our Google+ page.

As previously announced, we plan on updating the AdWords API to prevent a subset of modifications to the NetworkSetting for existing campaigns. This change affects all existing AdWords API versions.

Display-only campaigns have been evolving over time, and have developed unique features which make switching these campaigns between Display-only and other campaign types (Search-only or Search-and-Display) unreliable. Today, these modifications can unintentionally change campaign behavior (for instance, disabling certain display-specific targeting), potentially causing confusion and negatively impacting the advertiser experience. So starting 17 October 2013, we'll begin returning a TargetError.TARGET_ERROR error for such NetworkSetting changes.

If you do not make use of the NetworkSetting to change the network for existing campaigns, this change will not affect you. All other NetworkSetting modifications will continue to behave as before. The table below outlines changes possible between campaign settings:

Current setting Setting can be changed to
Display Network Only Search Network Only Search and Display Networks
Display Network Only - No No
Search Network Only No - Yes
Search and Display Networks No Yes -

As always, please feel free to ask any questions on the AdWords API forum or our Google+ page.