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

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.

 - Nicholas Chen, DFP API Team

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

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

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