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?
A segmentação por local permite exibir anúncios para usuários de uma região geográfica específica. Por exemplo, suponha que você esteja anunciando para uma cadeia de supermercados. Sem a segmentação por local, os 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 locais de supermercado. Assim, haveria a geração de custos e nenhuma possibilidade de retorno do investimento. Com a segmentação por local, as campanhas exibem anúncios somente nas regiões onde há supermercados abertos. Essa abordagem também permite segmentar diretamente os clientes que pesquisam localmente por supermercados.
Com a API Google Ads, é possível segmentar seus anúncios por país, região ou proximidade ao redor de um ponto geográfico específico.
Saiba mais sobre a segmentação de anúncios para localizações geográficas.
Campanhas de segmentação geográfica para uma região
Você pode segmentar campanhas para qualquer região geográfica em que o Google Ads seja compatível com a segmentação por local, por exemplo, um país, um estado, uma cidade ou uma região postal. Cada local segmentável é identificado exclusivamente por um ID de critério. É possível pesquisar um ID de critério usando
GeoTargetConstantService.SuggestGeoTargetConstants
.
O resource_name
de cada GeoTargetConstant
está
no formato geoTargetConstants/{Criterion ID}
. Por exemplo, o
valor resource_name
do estado de Nova York é geoTargetConstants/21167
.
Você pode adicionar segmentações por área geográfica às campanhas usando 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::V13::Resources::CampaignCriterion->new({ # Create a location using the specified location ID. location => Google::Ads::GoogleAds::V13::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::V13::Utils::ResourceNames::geo_target_constant( $location_id)} ), campaign => $campaign_resource_name }); return Google::Ads::GoogleAds::V13::Services::CampaignCriterionService::CampaignCriterionOperation ->new({ create => $campaign_criterion }); }
De vez em quando, o Google pode descontinuar alguns critérios de local por vários motivos:
a localização pode ser reestruturada em áreas menores ou maiores, mudanças
políticas, etc. Consulte o campo status
de um objeto
GeoTargetConstant para determinar se um local é
ENABLED
ou
REMOVAL_PLANNED
.
Leia mais sobre como as segmentações por local são descontinuadas.
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 procurar 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.V13.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([ 'locale' => $locale, 'countryCode' => $countryCode, 'locationNames' => 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::V13::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ê pode querer segmentar ainda mais precisamente uma cidade ou país. Por exemplo, você pode anunciar seus supermercados em até 10 km do local da loja. Nesses casos, é possível usar a
segmentação por proximidade.
O código para criar uma área de segmentação por proximidade é semelhante a adicionar uma segmentação por local, mas 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::V13::Resources::CampaignCriterion->new({ proximity => Google::Ads::GoogleAds::V13::Common::ProximityInfo->new({ address => Google::Ads::GoogleAds::V13::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::V13::Services::CampaignCriterionService::CampaignCriterionOperation ->new({ create => $campaign_criterion }); }
Recuperar segmentações geográficas
Você pode recuperar as segmentações geográficas de uma campanha usando GoogleAdsService.SearchStream
. É 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 os locais de segmentação de uma campanha, é necessário recuperar a lista de segmentações por área geográfica existentes e compará-la com a lista de novas segmentações. Em seguida, você pode usar a operação remove
para remover as segmentações desnecessárias e a operação create
para adicionar as novas segmentações geográficas necessárias, mas que estão faltando na campanha existente.
Excluir segmentações geográficas
Também é possível excluir LocationInfo
, mas não ProximityInfo
. Esse recurso é mais útil quando você quer
segmentar uma região, mas excluir uma sub-região. Por exemplo, segmentar todos os
estados dos 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
Ao usar uma LocationGroupInfo
, é possível ativar uma
campanha para várias regiões geográficas. Uma região é centralizada nos
locais definidos pelas extensões de local da campanha ou por um
Feed
opcional.
O raio definido no LocationGroupInfo
atribui uma região circular em torno de cada local e consiste em um objeto radius
, comprimento e radius_units
, que podem 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 que exista fora dos IDs de critério fornecidos será segmentado.
Veja algumas dicas para criar um LocationGroupInfo
:
LocationGroupInfo.feed
precisa ser oresource_name
de umFeed
(se umFeed
estiver sendo usado).LocationGroupInfo.feed
pode ser modificado apenas em açõesCREATE
. Não é possível modificar esse campo em açõesUPDATE
.Um erro
RESOURCE_NOT_FOUND
pode ocorrer ao adicionar umFeed
a umLocationGroup
devido a qualquer uma das seguintes causas:- O
Feed
não existe. - O
Feed
está inativo. - O
Feed
não tem atributos mapeados para os critérios da campanha de local.
- O
Se um Feed
pode ou não ser usado para determinar um LocationGroup
pode ser determinado
analisando as entradas FeedMapping
. Pelo menos um
FeedMapping
precisa ter um criterion_type
de LOCATION_EXTENSION_TARGETING
.
Esta é uma consulta do GAQL que retorna os feeds com o tipo de critério adequado de mapeamento de feeds:
SELECT
feed.id,
feed_mapping.criterion_type
FROM feed_mapping
WHERE feed.id = <feed id>
AND feed_mapping.criterion_type = LOCATION_EXTENSION_TARGETING