Google Ads Developer Blog: geotargeting

Sunset of deprecated Geo Region targeting options in Display & Video 360 API

Friday, November 20, 2020

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:

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.
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.
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:

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.
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.

- Trevor Mulchay, Display & Video 360 API Team

Sunsetting manual location extensions from feeds

Thursday, February 23, 2017

Update: The sunset date for manual location extensions and subsequent auto-migration has changed to June 24th, 2017.

At the moment, location extensions in AdWords can be sourced from two different places: a Google My Business account that is linked to your AdWords account or - for legacy users - manual location extensions created as feed items in AdWords.

What’s changing?
We’ll sunset manual location extensions on June 24th, 2017 for all legacy users. You’ll no longer be able to manually create and manage Feed and FeedItem with a corresponding FeedMapping of placeholderType 7 (location extensions) and placeholderType 77 (location targeting) after this date. Instead, create your locations in Google My Business and link them to your AdWords account as outlined in our Location Extensions guide. You can use the Google My Business API to manage your business locations at scale.

What you should do
Please migrate your code before June 24th, 2017 to avoid being impacted by this transition. See our guide for managing location extensions for further details, including an end-to-end code example. We recommend migrating your existing legacy locations alongside your code in order to have full control over your Google My Business account structure, test your setup, and avoid any downtime in location extension management. If you're not concerned about downtime, let us migrate your existing manual location extensions for you (you still have to migrate your code).

Auto-migration
All unmigrated manual location extensions stored in AdWords will be gradually auto-migrated starting from June 24th, 2017.

For each Customer Account with unmigrated manual location extensions, we'll pick all Manager Accounts at the lowest level of the manager hierarchy.
For each such Manager Account, we'll create a single Business Account in Google My Business managed by the administrative users of the original Manager Account and its managers. The name of this Business Account will be ‘AdWords (<cid>)’, where <cid> is the AdWords Customer ID of the original Manager Account.
We’ll also create Business Accounts in Google My Business for Customer Accounts not linked to any Manager Account. Those will be managed by the administrative users of the Customer Account.
For each unmigrated location in the Customer Account, we'll create a new unverified business location in that Business Account and label it with its AdWords Customer ID. The original manually created feed items representing that location in AdWords will be removed.
We'll replace all unmigrated location extension and location targeting feeds with new feeds linked to the shared Business Account created in Google My Business. In each feed, we'll set up a labelFilter based on the Customer ID to map each location to its original account.
Any existing CampaignFeed and AdGroupFeed will be recreated to match the original setup, including their matching functions.

If you have questions while you’re upgrading, please reach out to us on the AdWords API forum.

- Timo Bozsolik, AdWords API Team

Changes to the setting of positiveGeoTargetType in AdWords campaigns

Tuesday, August 2, 2016

In September 2016, we will disallow the setting of positiveGeoTargetType as AREA_OF_INTEREST for non-search campaigns. Existing non-search campaigns whose positiveGeoTargetType are set to AREA_OF_INTEREST will be automatically changed to DONT_CARE. Any requests that attempt to set this to AREA_OF_INTEREST for non-search campaigns will fail.

In addition, for search campaigns, the behavior of AREA_OF_INTEREST will be changed. If you use this setting, the campaign will primarily target a user's area of interest and secondarily his/her location of presence. In other words, if the area of the user’s interest is explicitly present in a search query, such as “flower delivery in NYC”, then it’ll be used. If the search query doesn’t include any areas of interest, say “flower delivery”, the physical location of the user performing the search will be used instead.

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

Thanet (Knack) Praneenararat, AdWords API Team

Adjusting the manual location extension sunset

Monday, February 1, 2016

In October 2015, we announced the Google My Business API and the sunset of manual location extensions in AdWords. To give developers more time to migrate their locations from AdWords to Google My Business, we have decided to extend the manual location extensions sunset and voluntary migration deadline beyond March 31. Existing locations in AdWords will not be auto-migrated until further notice. We will announce the revised sunset timeline and more details about auto-migration on this blog at a future date. Apologies for any inconvenience, please contact us if you have any questions.

Timo Bozsolik, AdWords API Team

New geo targeting options in AdWords API

Friday, March 21, 2014

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.

- Michael Cloonan, AdWords API Team

Migrating to the new and improved DFP Geo_Target table

Friday, December 20, 2013

v201311

More granularity in targeting

Streamlined code paths

Increased flexibility for handling location objects

Geo_Targetlook at this Python exampleParentIds

- Nicholas Chen, DFP API Team

Geography data changes in DFP and how they affect the API

Friday, February 8, 2013

We are constantly working to improve DFP to help our publishers serve ads in the best way possible. One recent improvement to DFP has been an update to the geography data used for targeting. This update also deprecates locations that may no longer exist, may be obsolete, or are no longer recognized. Any deprecated locations targeted by existing line items will be ignored, but still shown so you can update them appropriately.

Keeping our geography data up-to-date allows for more accurate ad targeting, which better helps publishers serve ads to their target audience. This update also lays the ground work for some further updates we have planned. These changes may affect how you use the API to integrate your product with DFP, so we wanted to give some tips to smooth out the transition.

All deprecated locations can be found by using PublisherQueryLanguage.select on the geo tables with the following query: "WHERE targetable = false"
When creating or updating line items with geo targeting, ensure that you are using the base Location object instead of one of the Location subtypes.
For developers who have cached any geo targeting tables, we recommend you update your local database of targetable locations. When doing so, ensure you examine the targetable field and mark it as deprecated or remove it from your local database so as not to use it in the future.

You may also notice some hierarchy changes in the new geo data. For example, some cities may no longer have a metro region. These changes are intentional as we work to better update and classify our geographic locations. If you have questions, please feel free to ask them on our forum.

To tie this all together, we have written an example that checks every line item in a network to see if it is targeting a deprecated location and needs to be updated. Doing this check will save you trouble later if you try to update a line item that is targeting a deprecated location as you will need to remove the deprecated location from targeting before DFP will allow you to make the update. A snippet of the example is as follows, and you can find the full example on the PHP client library google code site.

  // Find all untargetable locations.
  $untargetableLocationIds = getAllUntargetableLocations($user);
  printf("Found %d untargetable locations.\n",
      count($untargetableLocationIds));

  // Build a map of geo targets to the line items targeting them.
  $geoTargetToLineItemsMap = buildGeoTargetToLineItemsMap($user);

  // Find all the deprecated geo targets from that map.
  $lineItemsToUpdate = findLineItemsToUpdate($geoTargetToLineItemsMap,
      $untargetableLocationIds);

  $i = 0;
  // Print the line items that need to be updated.
  foreach ($lineItemsToUpdate as $geoTargetId => $lineItemIds) {
    printf("%d) The following line items are targeting deprecated location "
        . "%d and need to be updated: %s\n", $i, $geoTargetId, implode(', ',
        $lineItemIds));
    $i++;
  }

- Vincent Tsao, DFP API Team

Changes to advanced location targeting

Monday, April 9, 2012

Last year we exposed advanced location targeting settings in the AdWords API, using the GeoTargetTypeSetting object. Based on customer feedback we are now rolling out a series of changes to improve the power and clarity of this feature. The full details of these changes can be found on the Inside AdWords blog, but some highlights are:

The advanced location targeting settings now apply to Display Network traffic in addition to Google Search and the Search Network traffic.

The default value of the exclusion setting will be more restrictive for new campaigns, taking into account both the physical location and the area of interest. In API terms, GeoTargetTypeSetting.negativeGeoTargetType will default to DONT_CARE for new campaigns. The value will not be updated for existing campaigns.

The AdWords web interface has reworded the language used to describe these settings. If you provide a user interface you may want to update your language as well.

If you have any questions about these changes please reach out to us in the forum or during one of our office hours hangouts.

- Eric Koleda, AdWords API Team

Geotargeting in the DFA API

Monday, December 19, 2011

We’ve heard some questions recently about the degree that geotargeting is supported through our API. Let’s explore how geotargeting can be managed through the DFA API.First, here’s a reminder about how geotargeting works in the DoubleClick for Advertisers product. As explained in this help center article (DFA sign-in required), combining multiple locations even if they are within different geographic categories always results in an “OR” relationship between them. Targeting the countries Mexico and the United States alongside the Canadian province of Ontario will cause your ad to be displayed if the impression originates from the United States or Mexico or Ontario.Let’s see how this example plays out through the API. We need to use the State and Country classes. These classes contain extra fields that are filled in with descriptions when the objects are returned from our server. You only need to fill in the id field when you send us an object that represents a target criterion for an ad. As explained on our best practices page, our ID numbers rarely change and caching them locally is always a good idea. If you have to retrieve them, reference our example code and the ad service documentation.Once you have the numbers, you can retrieve your ad from our server and add the desired targets. For example, this Python code will add the United States, Mexico, and Ontario as desired targets to an ad:# Get the ad that needs geotargeting added. ad = ad_service.GetAd(targetable_ad_id)[0] # Create and add country targeting criteria. country_targeting_criteria = { 'exclude': 'False', 'countries': [{'id': UNITED_STATES_COUNTRY_ID}, {'id': MEXICO_COUNTRY_ID}] } ad['countryTargetingCriteria'] = country_targeting_criteria # Add state targeting. Provinces are considered states. ad['states'] = [{'id': ONTARIO_STATE_ID}] # Save changes. This ad now serves only when an impression originates from # the United States, Mexico, or Ontario. ad_save_result = ad_service.SaveAd(ad)[0]Remember that only ad types that extend TargetableAdBase are targetable. If you run into any problems or have questions about targeting through the API, we’d be glad to help on our forum.

- Joseph DiLallo, DFA API Team

Ads Developer Blog

Sunset of deprecated Geo Region targeting options in Display & Video 360 API

Sunsetting manual location extensions from feeds

Changes to the setting of positiveGeoTargetType in AdWords campaigns

Adjusting the manual location extension sunset

New geo targeting options in AdWords API

Migrating to the new and improved DFP Geo_Target table

Geography data changes in DFP and how they affect the API

Changes to advanced location targeting

Geotargeting in the DFA API

Labels

Archive

Feeds

Google Ads API [+]

AdWords API [+]

Google Ads scripts [+]

Content API for Shopping [+]

Google Ad Manager API [+]

DCM API [+]

Mobile Ads [+]

IMA SDK [+]