This guide describes location targeting, and how you can use the AdWords API to add, retrieve, and update location targeting for your campaigns. It also examines advanced geo-targeting concepts like physical location and location of interest, as well as how to run reports and evaluate your campaign’s geo performance.
Code examples in this guide use the AdWords API Java library. Check the complete list of client libraries for other languages. Also, note that using a client library is recommended, but optional; you may use any SOAP kit in the programming language of your choice to make calls to the API.
Why is geo targeting important?
Location targeting allows you to serve ads to users in a particular geographical region. For example, assume you’re advertising for a chain of supermarkets. Without location targeting, your ads would show in all regions worldwide, and your ads might receive clicks from users in regions where you have no supermarket locations. This generates cost while providing no possibility of a return on the investment. With location targeting, your campaigns show ads only in regions where you have open supermarkets. This approach also allows you to directly target customers searching locally for supermarkets.
The AdWords API allows you to target your ads by country, region, or proximity around a specific geographical point.
If you need to brush up on location targeting concepts, see this Help Center article.
Geo target campaigns for a region
You can target campaigns to a specific geographical region (e.g., country, state, city, postal region) for which Google Ads supports location targeting. Each targetable location is uniquely identified by a Criterion ID.
You can add geo targets to your campaigns using the CampaignCriterionService. The following code snippet shows how to target your campaigns to California (USA) and Mexico.
// Create locations. The IDs can be found in the documentation or // retrieved with the LocationCriterionService. Location california = new Location(); california.setId(21137L); Location mexico = new Location(); mexico.setId(2484L); List operations = new ArrayList(); for (Criterion criterion : new Criterion[] {california, mexico}) { CampaignCriterionOperation operation = new CampaignCriterionOperation(); CampaignCriterion campaignCriterion = new CampaignCriterion(); campaignCriterion.setCampaignId(campaignId); campaignCriterion.setCriterion(criterion); operation.setOperand(campaignCriterion); operation.setOperator(Operator.ADD); operations.add(operation); } CampaignCriterionReturnValue result = campaignCriterionService.mutate(operations .toArray(new CampaignCriterionOperation[operations.size()]));
As shown in the code, you need to create Location objects for each region you want to target, and add them using CampaignCriteronService.mutate(). In the example, 21137 is the code for California, while 2484 is the code for Mexico.
Google may occasionally phase out some location criteria for various reasons: the location may be restructured into smaller (or larger areas), geo-political changes, etc. Refer to the targetingStatus field of a Location object to determine if a location is ACTIVE, OBSOLETE, or PHASING_OUT. See this blog post for more details about phasing out location targets.
Look up location codes for a region
As mentioned above, you need to create a Location object with an appropriate code to target a region. You can use the LocationCriterionService to look up the criterion ID for a location. The following code example shows how to look up a location criterion ID by location name.
String[] locationNames = new String[] {“Quebec”}; Selector selector = new Selector(); selector.setFields(new String[] {“Id”, “LocationName”, “CanonicalName”, “DisplayType”, “ParentLocations”, “Reach”}); selector.setPredicates(new Predicate[] { // Location names must match exactly, only EQUALS and IN are // supported. new Predicate(“LocationName”, PredicateOperator.IN, locationNames), // Set the locale of the returned location names. new Predicate(“Locale”, PredicateOperator.EQUALS, new String[] {“en”}) }); // Make the get request. LocationCriterion[] locationCriteria = locationCriterionService.get(selector); // Display the resulting location criteria. for (LocationCriterion locationCriterion : locationCriteria) { String parentString = getParentLocationString(locationCriterion.getLocation().getParentLocations()); System.out.printf(“The search term ‘%s’ returned the location ‘%s (%d)’ of type ‘%s’ ” + “with parent locations ‘%s’ and reach ‘%d’.n”, locationCriterion.getSearchTerm(), locationCriterion.getLocation().getLocationName(), locationCriterion.getLocation().getId(), locationCriterion.getLocation().getDisplayType(), parentString, locationCriterion.getReach()); } /** * Helper function to format a string for parent locations. * * @param parents List of parent locations. * @return Formatted string representing parent locations. */ public static String getParentLocationString(Location[] parents) { StringBuilder sb = new StringBuilder(); if (parents != null) { for (Location parent : parents) { if (sb.length() > 0) { sb.append(“, “); } sb.append(String.format(“%s (%s)”, parent.getLocationName(), parent.getDisplayType())); } } else { sb.append(“N/A”); } return sb.toString(); }
The code example above generates the following output:
The search term ‘Quebec’ returned the location ‘Quebec'(20123) of type ‘Province’ with parent locations ‘Canada (Country)’ and reach ‘5070000’. The search term ‘Quebec’ returned the location ‘Quebec City'(1002624) of type ‘City’ with parent locations ‘Quebec (Province), Canada (Country), ‘ and reach ‘356000’.
You can now target Quebec (Province) using location code 20123, and Quebec City using the location code 1002624.
The LocationCriterionService allows for retrieval of a location’s parents. This is done by adding ParentLocations to the list of selector fields. For example, our previous code returned the location (Quebec City) as well as its parent location (Canada). This feature is useful if you want to display a hierarchical list of locations to your customers, or if you want to add inclusion or exclusion logic for locations when targeting your campaigns.
An important thing to remember while working with parent locations is that you shouldn’t make any assumptions about a location’s displayType in a hierarchy. For example, USA may be divided into states and further into cities, but this isn’t true for every country in the world.
You can use the LocationCriterionService more effectively if you know the location name somewhat accurately. The lookup will try to match the name you give it. If you want to retrieve the location codes for a large number of regions, it may be more efficient to save the list locally in a database and write your own location lookup logic. You can easily look up the codes for a location, or download the list of all codes, from the targets table, which is periodically updated with the latest targets.
Target campaigns for proximity to a location
There are ti
mes when you might want to target even more precisely than a city or country. For example, you may want to advertise your supermarkets within 10 kilometers of your shop location. In such cases, you can use proximity targeting. The code to create a proximity target is similar to adding a location target, except that you have to create a Proximity object instead of a Location object.
// Create the address whose surrounding area you want to target. Address myAddress = new Address(); address.setStreetAddress(“38 avenue de l’Opéra”); address.setCityName(“Paris”); address.setPostalCode(“75002”); address.setCountryCode(“FR”); // Use myAddress to create a Proximity object Proximity proximity = new Proximity(); proximity.address = myAddress; proximity.radiusDistanceUnits = ProximityDistanceUnits.KILOMETERS; proximity.radiusInUnits = 10;
Target campaigns to a polygon region
In the past, Google Ads allowed you to target your campaigns to a specified polygon region. However, polygon targets have been deprecated in favor of proximity regions, so you can no longer add a polygon target using the AdWords API. However, if you’re retrieving geo targets for an existing campaign, you may encounter one. You can use the API to remove an existing polygon target.
Retrieve geo targets
You can retrieve the geo targets for a campaign using the CampaignCriterionService.get() method. You can filter your results by CriteriaType to restrict the results to Location alone, and use paging to limit the number of targets you retrieve.
int offset = 0; // Create selector. Selector selector = new Selector(); selector.setFields(new String[] {“CampaignId”, “Id”, “CriteriaType”, “LocationName”}); selector.setOrdering(new OrderBy[] {new OrderBy(“Name”, SortOrder.ASCENDING)}); selector.setPredicates(new Predicate[] {new Predicate(“CriteriaType”, PredicateOperator.EQUALS, new String[] {“LOCATION”})}); selector.setPaging(new Paging(offset, PAGE_SIZE)); CampaignCriterionPage page = null; do { page = campaignCriterionService.get(selector); if (page.getEntries() != null) { // Display campaigns. for (CampaignCriterion campaignCriterion : page.getEntries()) { System.out.printf(“Campaign criterion with campaign id ‘%s’, criterion id ‘%s’, ” + “and type ‘%s’ was found.n”, campaignCriterion.getCampaignId(), campaignCriterion.getCriterion().getId(), campaignCriterion.getCriterion().getCriterionType()); } Thread.sleep(1000); } else { System.out.println(“No campaign criteria were found.”); } offset += PAGE_SIZE; selector.getPaging().setStartIndex(offset); } while (offset < page.getTotalNumEntries());
Note that if your campaign is targeting all countries and regions, you’ll get an empty list of location targets.
To update location targets for a campaign, you need to retrieve the list of existing location targets and compare it with the list of new targets. You can then use the REMOVE operator to remove the targets you don’t need, and the ADD operator to add the new geo targets you need (but are missing in the existing campaign). In the past, the AdWords API allowed you to overwrite the geo targeting of a campaign using the SET operator. However, this behavior is no longer supported and you’ll need to use the REMOVE + ADD combination when updating geo targets for your campaign.
Exclude geo targets
You can also exclude a region. This feature is most useful if you want to target a region, but exclude a sub-region (for example, to target the entire United States, except for New York City). To exclude a region, create a NegativeCampaignCriterion, with its criterion as the location to exclude.
// Add a negative campaign geo target. NegativeCampaignCriterion negativeCriterion = new NegativeCampaignCriterion(); negativeCriterion.campaignId = campaignId; negativeCriterion.criterion = locationToExclude;
Advanced geotargeting settings
Google Ads allows you to specify whether to show your ads to users by their physical location or by their location of interest. For example, assume you run a campaign for a flower shop, you target only New York City, and that “flowers” is a keyword in your campaign. Consider a user located in California, searching for “flowers in new york”: In this case, California is the physical location for the user, whereas New York is the location of interest.
You can add a GeoTargetTypeSetting to your campaign to decide whether to show your ads to users based on (1) the location the user searched for, (2) their physical location, or (3) either their location of interest or physical location.
Note: AOI is not supported for Display Network campaigns. LOP and DONT_CARE are the only supported options for Display Network campaigns.
Geo performance reporting
You can analyze the effectiveness of geo targeting in your campaigns by running the following two report types to get geo performance data:
- The Geo Performance report.
- The Criteria Performance report, filtering by CriteriaType=LOCATION or PROXIMITY to get performance data for a particular geo target.
See the Reporting guide for more information.
