Google Ads

Location Targeting  |  AdWords API  |  Google Developers

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
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();
Location mexico = new Location();

List operations = new ArrayList();
for (Criterion criterion : new Criterion[] {california, mexico}) {
  CampaignCriterionOperation operation = new CampaignCriterionOperation();
  CampaignCriterion campaignCriterion = new CampaignCriterion();

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
object with an appropriate code to target a region. You can use the
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 =
 System.out.printf("The search term '%s' returned the location '%s (%d)' of type '%s' "
     + "with parent locations '%s' and reach '%d'.n",
    locationCriterion.getLocation().getDisplayType(), parentString,

  * 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(),
   } else {
   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 times 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
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");

// 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
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(),
  } else {
    System.out.println("No campaign criteria were found.");
  offset += PAGE_SIZE;
} while (offset 

Note that if your campaign is targeting all countries and regions, you'll get an empty list of location targets.

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

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:

  1. The Geo Performance report.
  2. 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.

Leave a Reply

Your email address will not be published. Required fields are marked *

Back to top button