Page Summary
-
Location targeting allows you to serve ads to users in specific geographical areas, preventing wasted ad spend in irrelevant regions and enabling direct targeting of local customers.
-
Geo targeting campaigns for a region can be done using a Criterion ID, which uniquely identifies each targetable location and can be looked up using
GeoTargetConstantService.SuggestGeoTargetConstants. -
You can also look up location criterion IDs by location name using
GeoTargetConstantService.SuggestGeoTargetConstants. -
Proximity targeting allows you to target areas within a specified radius of a specific geographical point using a
ProximityInfoobject. -
Geo targets can be retrieved using
GoogleAdsService.SearchStream, updated by comparing existing and new targets, and excluded by setting thenegativefield totrueforLocationInfoobjects.
This guide describes location targeting, and how you can use the Google Ads API to add, retrieve, and update location targeting for your campaigns.
For information about targeting limits, see the Targeting Limits section of About Google Ads account limits.
Why is geo-targeting important?
Location targeting lets you 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 lets you directly target customers searching locally for supermarkets.
The Google Ads API lets you target your ads by country, region, or proximity around a specific geographical point.
Learn more about Targeting ads to geographic locations.
Geo-target campaigns for a region
You can target campaigns to any geographical region for which Google Ads
supports location targeting, such as a country, a state, a city, or a postal
region. Each targetable location is uniquely identified by a Criterion ID. You
can look up a criterion ID using
GeoTargetConstantService.SuggestGeoTargetConstants.
The resource_name of each
GeoTargetConstant is of the form
geoTargetConstants/{Criterion ID}. For example, the resource_name value of
New York state is geoTargetConstants/21167.
You can add geo targets to your campaigns using the
CampaignCriterionService. The
following code snippet shows how to target your campaign with a criterion ID.
Java
private static CampaignCriterion buildLocationIdCriterion( long locationId, String campaignResourceName) { Builder criterionBuilder = CampaignCriterion.newBuilder().setCampaign(campaignResourceName); criterionBuilder .getLocationBuilder() .setGeoTargetConstant(ResourceNames.geoTargetConstant(locationId)); return criterionBuilder.build(); }
C#
private CampaignCriterion buildLocationCriterion(long locationId, string campaignResourceName) { GeoTargetConstantName location = new GeoTargetConstantName(locationId.ToString()); return new CampaignCriterion() { Campaign = campaignResourceName, Location = new LocationInfo() { GeoTargetConstant = location.ToString() } }; }
PHP
private static function createLocationCampaignCriterionOperation( int $locationId, string $campaignResourceName ) { // Constructs a campaign criterion for the specified campaign ID using the specified // location ID. $campaignCriterion = new CampaignCriterion([ // Creates a location using the specified location ID. 'location' => new LocationInfo([ // Besides using location ID, you can also search by location names using // GeoTargetConstantServiceClient::suggestGeoTargetConstants() and directly // apply GeoTargetConstant::$resourceName here. An example can be found // in GetGeoTargetConstantByNames.php. 'geo_target_constant' => ResourceNames::forGeoTargetConstant($locationId) ]), 'campaign' => $campaignResourceName ]); return new CampaignCriterionOperation(['create' => $campaignCriterion]); }
Python
def create_location_op( client: GoogleAdsClient, customer_id: str, campaign_id: str, location_id: str, ) -> CampaignCriterionOperation: campaign_service: CampaignServiceClient = client.get_service( "CampaignService" ) geo_target_constant_service: GeoTargetConstantServiceClient = ( client.get_service("GeoTargetConstantService") ) # Create the campaign criterion. campaign_criterion_operation: CampaignCriterionOperation = client.get_type( "CampaignCriterionOperation" ) campaign_criterion: CampaignCriterion = campaign_criterion_operation.create campaign_criterion.campaign = campaign_service.campaign_path( customer_id, campaign_id ) # Besides using location_id, you can also search by location names from # GeoTargetConstantService.suggest_geo_target_constants() and directly # apply GeoTargetConstant.resource_name here. An example can be found # in get_geo_target_constant_by_names.py. campaign_criterion.location.geo_target_constant = ( geo_target_constant_service.geo_target_constant_path(location_id) ) return campaign_criterion_operation
Ruby
def create_location(client, customer_id, campaign_id, location_id) client.operation.create_resource.campaign_criterion do |criterion| criterion.campaign = client.path.campaign(customer_id, campaign_id) criterion.location = client.resource.location_info do |li| # Besides using location_id, you can also search by location names from # GeoTargetConstantService.suggest_geo_target_constants() and directly # apply GeoTargetConstant.resource_name here. An example can be found # in get_geo_target_constant_by_names.rb. li.geo_target_constant = client.path.geo_target_constant(location_id) end end end
Perl
sub create_location_campaign_criterion_operation { my ($location_id, $campaign_resource_name) = @_; # Construct a campaign criterion for the specified campaign using the # specified location ID. my $campaign_criterion = Google::Ads::GoogleAds::V22::Resources::CampaignCriterion->new({ # Create a location using the specified location ID. location => Google::Ads::GoogleAds::V22::Common::LocationInfo->new({ # Besides using location ID, you can also search by location names # using GeoTargetConstantService::suggest() and directly apply # GeoTargetConstant->{resourceName} here. An example can be found # in get_geo_target_constants_by_names.pl. geoTargetConstant => Google::Ads::GoogleAds::V22::Utils::ResourceNames::geo_target_constant( $location_id)} ), campaign => $campaign_resource_name }); return Google::Ads::GoogleAds::V22::Services::CampaignCriterionService::CampaignCriterionOperation ->new({ create => $campaign_criterion }); }
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 status field of
a GeoTargetConstant object to determine if a location is
ENABLED
or
REMOVAL_PLANNED.
Look up by location name
You can also look up the criterion ID by location name using
GeoTargetConstantService.SuggestGeoTargetConstants.
The following code example shows how to look up a location criterion ID by
location name.
Java
private void runExample(GoogleAdsClient googleAdsClient) { try (GeoTargetConstantServiceClient geoTargetClient = googleAdsClient.getLatestVersion().createGeoTargetConstantServiceClient()) { SuggestGeoTargetConstantsRequest.Builder requestBuilder = SuggestGeoTargetConstantsRequest.newBuilder(); // Locale is using ISO 639-1 format. If an invalid locale is given, 'en' is used by default. requestBuilder.setLocale("en"); // A list of country codes can be referenced here: // https://developers.google.com/google-ads/api/reference/data/geotargets requestBuilder.setCountryCode("FR"); requestBuilder .getLocationNamesBuilder() .addAllNames(ImmutableList.of("Paris", "Quebec", "Spain", "Deutschland")); SuggestGeoTargetConstantsResponse response = geoTargetClient.suggestGeoTargetConstants(requestBuilder.build()); for (GeoTargetConstantSuggestion suggestion : response.getGeoTargetConstantSuggestionsList()) { System.out.printf( "%s (%s,%s,%s,%s) is found in locale (%s) with reach (%d) for search term (%s).%n", suggestion.getGeoTargetConstant().getResourceName(), suggestion.getGeoTargetConstant().getName(), suggestion.getGeoTargetConstant().getCountryCode(), suggestion.getGeoTargetConstant().getTargetType(), suggestion.getGeoTargetConstant().getStatus().name(), suggestion.getLocale(), suggestion.getReach(), suggestion.getSearchTerm()); } } }
C#
public void Run(GoogleAdsClient client) { // Get the GeoTargetConstantServiceClient. GeoTargetConstantServiceClient geoService = client.GetService(Services.V22.GeoTargetConstantService); // Locale is using ISO 639-1 format. If an invalid locale is given, // 'en' is used by default. string locale = "en"; // A list of country codes can be referenced here: // https://developers.google.com/google-ads/api/reference/data/geotargets string countryCode = "FR"; string[] locations = { "Paris", "Quebec", "Spain", "Deutschland" }; SuggestGeoTargetConstantsRequest request = new SuggestGeoTargetConstantsRequest() { Locale = locale, CountryCode = countryCode, LocationNames = new SuggestGeoTargetConstantsRequest.Types.LocationNames() }; request.LocationNames.Names.AddRange(locations); try { SuggestGeoTargetConstantsResponse response = geoService.SuggestGeoTargetConstants(request); foreach (GeoTargetConstantSuggestion suggestion in response.GeoTargetConstantSuggestions) { Console.WriteLine( $"{suggestion.GeoTargetConstant.ResourceName} " + $"({suggestion.GeoTargetConstant.Name}, " + $"{suggestion.GeoTargetConstant.CountryCode}, " + $"{suggestion.GeoTargetConstant.TargetType}, " + $"{suggestion.GeoTargetConstant.Status}) is found in locale " + $"({suggestion.Locale}) with reach ({suggestion.Reach}) " + $"for search term ({suggestion.SearchTerm})."); } } catch (GoogleAdsException e) { Console.WriteLine("Failure:"); Console.WriteLine($"Message: {e.Message}"); Console.WriteLine($"Failure: {e.Failure}"); Console.WriteLine($"Request ID: {e.RequestId}"); throw; } }
PHP
public static function runExample( GoogleAdsClient $googleAdsClient, array $locationNames, string $locale, string $countryCode ) { $geoTargetConstantServiceClient = $googleAdsClient->getGeoTargetConstantServiceClient(); $response = $geoTargetConstantServiceClient->suggestGeoTargetConstants( new SuggestGeoTargetConstantsRequest([ 'locale' => $locale, 'country_code' => $countryCode, 'location_names' => new LocationNames(['names' => $locationNames]) ]) ); // Iterates over all geo target constant suggestion objects and prints the requested field // values for each one. foreach ($response->getGeoTargetConstantSuggestions() as $geoTargetConstantSuggestion) { /** @var GeoTargetConstantSuggestion $geoTargetConstantSuggestion */ printf( "Found '%s' ('%s','%s','%s',%s) in locale '%s' with reach %d" . " for the search term '%s'.%s", $geoTargetConstantSuggestion->getGeoTargetConstant()->getResourceName(), $geoTargetConstantSuggestion->getGeoTargetConstant()->getName(), $geoTargetConstantSuggestion->getGeoTargetConstant()->getCountryCode(), $geoTargetConstantSuggestion->getGeoTargetConstant()->getTargetType(), GeoTargetConstantStatus::name( $geoTargetConstantSuggestion->getGeoTargetConstant()->getStatus() ), $geoTargetConstantSuggestion->getLocale(), $geoTargetConstantSuggestion->getReach(), $geoTargetConstantSuggestion->getSearchTerm(), PHP_EOL ); } }
Python
def main(client: GoogleAdsClient) -> None: gtc_service: GeoTargetConstantServiceClient = client.get_service( "GeoTargetConstantService" ) gtc_request: SuggestGeoTargetConstantsRequest = client.get_type( "SuggestGeoTargetConstantsRequest" ) gtc_request.locale = LOCALE gtc_request.country_code = COUNTRY_CODE # The location names to get suggested geo target constants. # Type hint for gtc_request.location_names.names is not straightforward # as it's part of a complex protobuf object. gtc_request.location_names.names.extend( ["Paris", "Quebec", "Spain", "Deutschland"] ) results: SuggestGeoTargetConstantsResponse = ( gtc_service.suggest_geo_target_constants(gtc_request) ) suggestion: GeoTargetConstantSuggestion for suggestion in results.geo_target_constant_suggestions: geo_target_constant: GeoTargetConstant = suggestion.geo_target_constant print( f"{geo_target_constant.resource_name} " f"({geo_target_constant.name}, " f"{geo_target_constant.country_code}, " f"{geo_target_constant.target_type}, " f"{geo_target_constant.status.name}) " f"is found in locale ({suggestion.locale}) " f"with reach ({suggestion.reach}) " f"from search term ({suggestion.search_term})." )
Ruby
def get_geo_target_constants_by_names # GoogleAdsClient will read a config file from # ENV['HOME']/google_ads_config.rb when called without parameters client = Google::Ads::GoogleAds::GoogleAdsClient.new gtc_service = client.service.geo_target_constant location_names = client.resource.location_names do |ln| ['Paris', 'Quebec', 'Spain', 'Deutschland'].each do |name| ln.names << name end end # Locale is using ISO 639-1 format. If an invalid locale is given, # 'en' is used by default. locale = 'en' # A list of country codes can be referenced here: # https://developers.google.com/google-ads/api/reference/data/geotargets country_code = 'FR' response = gtc_service.suggest_geo_target_constants( locale: locale, country_code: country_code, location_names: location_names ) response.geo_target_constant_suggestions.each do |suggestion| puts sprintf("%s (%s,%s,%s,%s) is found in locale (%s) with reach (%d)" \ " from search term (%s).", suggestion.geo_target_constant.resource_name, suggestion.geo_target_constant.name, suggestion.geo_target_constant.country_code, suggestion.geo_target_constant.target_type, suggestion.geo_target_constant.status, suggestion.locale, suggestion.reach, suggestion.search_term) end end
Perl
sub get_geo_target_constants_by_names { my ($api_client, $location_names, $locale, $country_code) = @_; my $suggest_response = $api_client->GeoTargetConstantService()->suggest({ locale => $locale, countryCode => $country_code, locationNames => Google::Ads::GoogleAds::V22::Services::GeoTargetConstantService::LocationNames ->new({ names => $location_names })}); # Iterate over all geo target constant suggestion objects and print the requested # field values for each one. foreach my $geo_target_constant_suggestion ( @{$suggest_response->{geoTargetConstantSuggestions}}) { printf "Found '%s' ('%s','%s','%s',%s) in locale '%s' with reach %d" . " for the search term '%s'.\n", $geo_target_constant_suggestion->{geoTargetConstant}{resourceName}, $geo_target_constant_suggestion->{geoTargetConstant}{name}, $geo_target_constant_suggestion->{geoTargetConstant}{countryCode}, $geo_target_constant_suggestion->{geoTargetConstant}{targetType}, $geo_target_constant_suggestion->{geoTargetConstant}{status}, $geo_target_constant_suggestion->{locale}, $geo_target_constant_suggestion->{reach}, $geo_target_constant_suggestion->{searchTerm}; } return 1; }
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 ProximityInfo object
instead of a LocationInfo object.
Java
private static CampaignCriterion buildProximityLocation(String campaignResourceName) { Builder builder = CampaignCriterion.newBuilder().setCampaign(campaignResourceName); ProximityInfo.Builder proximityBuilder = builder.getProximityBuilder(); proximityBuilder.setRadius(10.0).setRadiusUnits(ProximityRadiusUnits.MILES); AddressInfo.Builder addressBuilder = proximityBuilder.getAddressBuilder(); addressBuilder .setStreetAddress("38 avenue de l'Opéra") .setCityName("Paris") .setPostalCode("75002") .setCountryCode("FR"); return builder.build(); }
C#
private CampaignCriterion buildProximityCriterion(string campaignResourceName) { ProximityInfo proximity = new ProximityInfo() { Address = new AddressInfo() { StreetAddress = "38 avenue de l'Opéra", CityName = "Paris", PostalCode = "75002", CountryCode = "FR" }, Radius = 10d, // Default is kilometers. RadiusUnits = ProximityRadiusUnits.Miles }; return new CampaignCriterion() { Campaign = campaignResourceName, Proximity = proximity }; }
PHP
private static function createProximityCampaignCriterionOperation(string $campaignResourceName) { // Constructs a campaign criterion as a proximity. $campaignCriterion = new CampaignCriterion([ 'proximity' => new ProximityInfo([ 'address' => new AddressInfo([ 'street_address' => '38 avenue de l\'Opéra', 'city_name' => 'Paris', 'postal_code' => '75002', 'country_code' => 'FR', ]), 'radius' => 10.0, // Default is kilometers. 'radius_units' => ProximityRadiusUnits::MILES ]), 'campaign' => $campaignResourceName ]); return new CampaignCriterionOperation(['create' => $campaignCriterion]); }
Python
def create_proximity_op( client: GoogleAdsClient, customer_id: str, campaign_id: str ) -> CampaignCriterionOperation: campaign_service: CampaignServiceClient = client.get_service( "CampaignService" ) # Create the campaign criterion. campaign_criterion_operation: CampaignCriterionOperation = client.get_type( "CampaignCriterionOperation" ) campaign_criterion: CampaignCriterion = campaign_criterion_operation.create campaign_criterion.campaign = campaign_service.campaign_path( customer_id, campaign_id ) campaign_criterion.proximity.address.street_address = "38 avenue de l'Opera" campaign_criterion.proximity.address.city_name = "Paris" campaign_criterion.proximity.address.postal_code = "75002" campaign_criterion.proximity.address.country_code = "FR" campaign_criterion.proximity.radius = 10 # Default is kilometers. campaign_criterion.proximity.radius_units = ( client.enums.ProximityRadiusUnitsEnum.MILES ) return campaign_criterion_operation
Ruby
def create_proximity(client, customer_id, campaign_id) client.operation.create_resource.campaign_criterion do |criterion| criterion.campaign = client.path.campaign(customer_id, campaign_id) criterion.proximity = client.resource.proximity_info do |proximity| proximity.address = client.resource.address_info do |address| address.street_address = "38 avenue de l'Opéra" address.city_name = "Paris" address.postal_code = "75002" address.country_code = "FR" end proximity.radius = 10 proximity.radius_units = :MILES end end end
Perl
sub create_proximity_campaign_criterion_operation { my ($campaign_resource_name) = @_; # Construct a campaign criterion as a proximity. my $campaign_criterion = Google::Ads::GoogleAds::V22::Resources::CampaignCriterion->new({ proximity => Google::Ads::GoogleAds::V22::Common::ProximityInfo->new({ address => Google::Ads::GoogleAds::V22::Common::AddressInfo->new({ streetAddress => "38 avenue de l'Opéra", cityName => "cityName", postalCode => "75002", countryCode => "FR" } ), radius => 10.0, # Default is kilometers. radiusUnits => MILES } ), campaign => $campaign_resource_name }); return Google::Ads::GoogleAds::V22::Services::CampaignCriterionService::CampaignCriterionOperation ->new({ create => $campaign_criterion }); }
Retrieve geo-targets
You can retrieve the geo targets for a campaign using the
GoogleAdsService.SearchStream.
You can filter your results in the WHERE clause.
SELECT
campaign_criterion.campaign,
campaign_criterion.location.geo_target_constant,
campaign_criterion.proximity.geo_point.longitude_in_micro_degrees,
campaign_criterion.proximity.geo_point.latitude_in_micro_degrees,
campaign_criterion.proximity.radius,
campaign_criterion.negative
FROM campaign_criterion
WHERE
campaign_criterion.campaign = 'customers/{customer_id}/campaigns/{campaign_id}'
AND campaign_criterion.type IN (LOCATION, PROXIMITY)
Update geo-targets
To update location targets for a campaign, you need to retrieve the list of
existing geo targets and compare it with the list of new targets. You can then
use the remove operation to remove the targets you don't need, and the
create operation to add the new geo targets you need (but are missing in the
existing campaign).
Exclude geo-targets
You can also exclude LocationInfo, but not
ProximityInfo. 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, set
the negative field in
CampaignCriterion to be true.
Target multiple geographic regions
Using a LocationGroupInfo, you can enable a
campaign to target multiple geographic regions. A region is centered on the
locations defined by the location extensions of the campaign.
The radius defined on the LocationGroupInfo ascribes a circular region around
each location, and consists of a radius object, length, and radius_units, which can be either meters or
miles (LocationGroupRadiusUnitsEnum).
The locations in a LocationGroupInfo can be filtered by a list of geotargeting
criterion IDs prescribed in the
geo_target_constant field. If defined, no locations that exist outside of
the given criteria IDs will be targeted.
Advanced location options with GeoTargetTypeSetting
Beyond specifying locations to target or exclude, you can refine how Google Ads
matches users to these locations using advanced location options. These settings
are managed through
Campaign.GeoTargetTypeSetting.
This setting consists of two fields:
positive_geo_target_type: Determines how users are matched for locations you target.negative_geo_target_type: Determines how users are matched for locations you exclude.
Positive targeting settings (positive_geo_target_type)
You can choose from the following options for your positive location targeting,
using values from the
PositiveGeoTargetTypeEnum:
PRESENCE_OR_INTEREST(Recommended Default):- Reaches people who are likely to be in, or regularly in, your targeted locations, PLUS people who have shown interest in your targeted locations.
- Interest can be signaled by search terms, past visits, or content consumed related to the location.
- This option provides the broadest reach.
PRESENCE:- Reaches only people who are likely to be physically located or regularly in your targeted locations.
- This is more restrictive and useful if your services or products are strictly limited to people physically present in an area.
Note: Other values like SEARCH_INTEREST are deprecated and no longer settable
for most campaign types.
Negative targeting settings (negative_geo_target_type)
For locations you want to exclude, you use the
NegativeGeoTargetTypeEnum:
PRESENCE(Recommended Default):- Excludes people who are likely to be physically located in the locations you've excluded.
- People outside the excluded areas, even if interested in them, may still see your ads, provided they match your positive targeting.
Note: The PRESENCE_OR_INTEREST value is generally not supported for negative
geotargeting in most campaign types.
Manage advanced location options
You can control these settings by updating the
Campaign.geo_target_type_setting object.
Example: Setting a campaign to target by PRESENCE only
Here's a conceptual example of how you might structure an API call to modify the
positive_geo_target_type. The exact code will vary based on the client library
language.
// Conceptual structure for a Campaign update operation
operations {
update {
resource_name: "customers/{customer_id}/campaigns/{campaign_id}"
geo_target_type_setting {
positive_geo_target_type: PRESENCE
// negative_geo_target_type remains at its default PRESENCE if not specified
}
}
update_mask {
paths: "geo_target_type_setting.positive_geo_target_type"
}
}
To fetch the current settings, include
campaign.geo_target_type_setting.positive_geo_target_type and
campaign.geo_target_type_setting.negative_geo_target_type in your
GoogleAdsService search query.
By configuring these settings, you gain more granular control over who sees your ads based on their relationship to the geographic locations you've specified, aligning more closely with your business goals.