Este guia descreve a segmentação por local e o modo de usar a Google Ads API para adicionar, recuperar e atualizar segmentações por local para suas campanhas.
Por que a segmentação geográfica é importante?
Com a segmentação por local, você pode veicular anúncios para usuários em uma região geográfica específica. Por exemplo, suponha que você esteja anunciando uma rede de supermercados. Sem a segmentação por local, seus anúncios seriam exibidos em todas as regiões do mundo e poderiam receber cliques de usuários em regiões onde você não tem supermercados. Assim, haveria a geração de custos e nenhuma possibilidade de retorno do investimento. Com a segmentação por local, suas campanhas mostram anúncios apenas nas regiões onde você tem supermercados abertos. Essa abordagem também permite segmentar diretamente os clientes que pesquisam supermercados na região.
Com a API Google Ads, é possível segmentar seus anúncios por país, região ou proximidade em torno de um ponto geográfico específico.
Saiba mais sobre Segmentar anúncios para localizações geográficas.
Campanhas de segmentação geográfica para uma região
É possível segmentar campanhas para qualquer região geográfica em que o Google Ads ofereça suporte à segmentação por local, como um país, um estado, uma cidade ou uma região postal. Cada local segmentável é identificado de forma exclusiva por um ID de critério. É possível pesquisar um ID de critério usando
GeoTargetConstantService.SuggestGeoTargetConstants
.
O resource_name
de cada GeoTargetConstant
é do formato geoTargetConstants/{Criterion ID}
. Por exemplo, o valor de resource_name
do estado de Nova York é geoTargetConstants/21167
.
Você pode adicionar segmentações geográficas às suas campanhas usando o
CampaignCriterionService
. O snippet de código a seguir mostra como segmentar sua campanha com um ID de critério.
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, customer_id, campaign_id, location_id): campaign_service = client.get_service("CampaignService") geo_target_constant_service = client.get_service("GeoTargetConstantService") # Create the campaign criterion. campaign_criterion_operation = client.get_type("CampaignCriterionOperation") campaign_criterion = 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::V20::Resources::CampaignCriterion->new({ # Create a location using the specified location ID. location => Google::Ads::GoogleAds::V20::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::V20::Utils::ResourceNames::geo_target_constant( $location_id)} ), campaign => $campaign_resource_name }); return Google::Ads::GoogleAds::V20::Services::CampaignCriterionService::CampaignCriterionOperation ->new({ create => $campaign_criterion }); }
O Google pode desativar alguns critérios de local por vários motivos: reestruturação do local em áreas menores ou maiores, mudanças geopolíticas etc. Consulte o campo status
de um objeto GeoTargetConstant
para determinar se um local está ENABLED
ou REMOVAL_PLANNED
.
Saiba mais sobre como os locais de segmentação são desativados.
Pesquisar pelo nome do local
Também é possível pesquisar o ID do critério pelo nome do local usando
GeoTargetConstantService.SuggestGeoTargetConstants
.
O exemplo de código a seguir mostra como pesquisar um ID de critério de local pelo nome do local.
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.V20.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): gtc_service = client.get_service("GeoTargetConstantService") gtc_request = client.get_type("SuggestGeoTargetConstantsRequest") gtc_request.locale = LOCALE gtc_request.country_code = COUNTRY_CODE # The location names to get suggested geo target constants. gtc_request.location_names.names.extend( ["Paris", "Quebec", "Spain", "Deutschland"] ) results = gtc_service.suggest_geo_target_constants(gtc_request) for suggestion in results.geo_target_constant_suggestions: geo_target_constant = 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::V20::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; }
Segmentar campanhas por proximidade com um local
Às vezes, você quer segmentar com mais precisão do que uma cidade ou um país. Por exemplo, você pode anunciar seus supermercados em um raio de 10 quilômetros da sua loja. Nesses casos, use a segmentação por proximidade.
O código para criar uma segmentação por proximidade é semelhante ao de uma segmentação por local, exceto que você precisa criar um objeto ProximityInfo
em vez de um objeto LocationInfo
.
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, customer_id, campaign_id): campaign_service = client.get_service("CampaignService") # Create the campaign criterion. campaign_criterion_operation = client.get_type("CampaignCriterionOperation") campaign_criterion = 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::V20::Resources::CampaignCriterion->new({ proximity => Google::Ads::GoogleAds::V20::Common::ProximityInfo->new({ address => Google::Ads::GoogleAds::V20::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::V20::Services::CampaignCriterionService::CampaignCriterionOperation ->new({ create => $campaign_criterion }); }
Recuperar segmentações geográficas
Use o
GoogleAdsService.SearchStream
para recuperar as segmentações geográficas de uma campanha.
É possível filtrar os resultados na cláusula WHERE
.
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)
Atualizar as segmentações geográficas
Para atualizar as segmentações por local de uma campanha, recupere a lista de segmentações geográficas atuais e compare com a lista de novas segmentações. Em seguida, use a operação remove
para remover os destinos que não são necessários e a operação create
para adicionar os novos destinos geográficos que você precisa, mas que estão faltando na campanha atual.
Excluir segmentações geográficas
Também é possível excluir LocationInfo
, mas não
ProximityInfo
. Esse recurso é mais útil se você quiser segmentar uma região, mas excluir uma sub-região (por exemplo, para segmentar todos os Estados Unidos, exceto a cidade de Nova York). Para excluir uma região, defina o campo negative
em CampaignCriterion
como true
.
Segmentar várias regiões geográficas
Com um LocationGroupInfo
, é possível ativar uma campanha para segmentar várias regiões geográficas. Uma região é centralizada nos locais definidos pelas extensões de local da campanha.
O raio definido no LocationGroupInfo
atribui uma região circular ao redor de cada local e consiste em um objeto radius
, comprimento e radius_units
, que pode ser metros ou milhas (LocationGroupRadiusUnitsEnum
).
Os locais em um LocationGroupInfo
podem ser filtrados por uma lista de IDs de critério de segmentação geográfica prescritos no campo geo_target_constant
. Se definido, nenhum local fora dos IDs de critério especificados será segmentado.