Bu kılavuzda, yer hedeflemenin yanı sıra kampanyalarınız için konum hedeflemeyi eklemek, almak ve güncellemek amacıyla Google Ads API'yi nasıl kullanabileceğiniz açıklanmaktadır.
Coğrafi hedefleme neden önemlidir?
Yer hedefleme, reklamları belirli bir coğrafi bölgedeki kullanıcılara sunmanıza olanak tanır. Örneğin, bir süpermarket zincirinin reklamını yaptığınızı varsayalım. Yer hedefleme olmasaydı, reklamlarınız dünyadaki tüm bölgelerde gösterilir ve reklamlarınız süpermarket konumlarınızın bulunmadığı bölgelerdeki kullanıcılardan tıklama alabilir. Bu da maliyet oluşturur ve yatırım getirisi sağlanma ihtimalini ortadan kaldırır. Yer hedefleme sayesinde, kampanyalarınız yalnızca açık süpermarketlerinizin bulunduğu bölgelerde reklam gösterir. Bu yaklaşım, bölgenizde süpermarket arayan müşterileri doğrudan hedeflemenize de olanak tanır.
Google Ads API'si, reklamlarınızla ülke, bölge veya belirli bir coğrafi noktanın çevresindeki yakınlığa göre hedeflemenize olanak tanır.
Reklamlarla coğrafi konumları hedefleme hakkında daha fazla bilgi edinin.
Bir bölge için coğrafi hedefleme kampanyaları
Kampanyaları, Google Ads'in yer hedeflemeyi desteklediği herhangi bir coğrafi bölgeye (ör. ülke, eyalet, şehir veya posta bölgesi) hedefleyebilirsiniz. Her hedeflenebilir konum, bir Ölçüt Kimliği ile benzersiz bir şekilde tanımlanır. GeoTargetConstantService.SuggestGeoTargetConstants kullanarak ölçüt kimliğini arayabilirsiniz.
Her bir GeoTargetConstant öğesinin resource_name değeri geoTargetConstants/{Criterion ID} biçimindedir. Örneğin, New York eyaletinin resource_name değeri geoTargetConstants/21167'dır.
CampaignCriterionService kullanarak kampanyalarınıza coğrafi hedefler ekleyebilirsiniz. Aşağıdaki kod snippet'i, kampanyanızı ölçüt kimliğiyle nasıl hedefleyeceğinizi gösterir.
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::V16::Resources::CampaignCriterion->new({
# Create a location using the specified location ID.
location => Google::Ads::GoogleAds::V16::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::V16::Utils::ResourceNames::geo_target_constant(
$location_id)}
),
campaign => $campaign_resource_name
});
return
Google::Ads::GoogleAds::V16::Services::CampaignCriterionService::CampaignCriterionOperation
->new({
create => $campaign_criterion
});
}
Google, çeşitli nedenlerle zaman zaman bazı konum ölçütlerini aşamalı olarak kullanımdan kaldırabilir: Konum, daha küçük veya daha büyük alanlara, jeopolitik değişiklikler vb. şeklinde yeniden yapılandırılabilir. Bir konumun ENABLED veya REMOVAL_PLANNED olup olmadığını belirlemek için GeoTargetConstant nesnesinin status alanına bakın.
Konum hedeflerinin nasıl kullanımdan kaldırıldığı hakkında daha fazla bilgi edinin.
Konum adına göre ara
GeoTargetConstantService.SuggestGeoTargetConstants kullanarak ölçüt kimliğini konum adına göre de arayabilirsiniz.
Aşağıdaki kod örneğinde, konum ölçütü kimliğinin konum adına göre nasıl aranacağı gösterilmektedir.
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.V16.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::V16::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;
}
Bir konuma yakınlığı hedefleme kampanyaları
Bazı durumlarda bir şehir veya ülkeden daha hassas hedefleme yapmak isteyebilirsiniz. Örneğin, mağazanızın bulunduğu yere en fazla 10 kilometre uzaklıktaki
süpermarketlerinizin reklamını yapmak isteyebilirsiniz. Bu gibi durumlarda, yakın çevredeki hedef özelliğini kullanabilirsiniz.
Bir yakın çevredeki hedef oluşturmak için kullanılacak kod, konum hedefi eklemeye benzer ancak LocationInfo nesnesi yerine ProximityInfo nesnesi oluşturmanız gerekir.
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::V16::Resources::CampaignCriterion->new({
proximity => Google::Ads::GoogleAds::V16::Common::ProximityInfo->new({
address => Google::Ads::GoogleAds::V16::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::V16::Services::CampaignCriterionService::CampaignCriterionOperation
->new({
create => $campaign_criterion
});
}
Coğrafi hedefleri alma
Bir kampanyanın coğrafi hedeflerini GoogleAdsService.SearchStream kullanarak alabilirsiniz. Sonuçlarınızı WHERE ifadesinde filtreleyebilirsiniz.
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)
Coğrafi hedefleri güncelle
Bir kampanyanın konum hedeflerini güncellemek için mevcut coğrafi hedeflerin listesini almanız ve yeni hedefler listesiyle karşılaştırmanız gerekir. Ardından, ihtiyacınız olmayan hedefleri kaldırmak için remove işlemini ve ihtiyacınız olan (ancak mevcut kampanyada bulunmayan) yeni coğrafi hedefleri eklemek için create işlemini kullanabilirsiniz.
Coğrafi hedefleri hariç tutma
Ayrıca LocationInfo öğesini hariç tutabilirsiniz ancak ProximityInfo öğesini hariç tutamazsınız. Bu özellik en çok, bir bölgeyi hedeflerken bir alt bölgeyi hariç tutmak (örneğin, New York City hariç ABD'nin tamamını hedeflemek) istiyorsanız kullanışlıdır. Bir bölgeyi hariç tutmak için CampaignCriterion içindeki negative alanını true olacak şekilde ayarlayın.
Birden çok coğrafi bölgeyi hedefleme
LocationGroupInfo kullanarak bir kampanyanın birden çok coğrafi bölgeyi hedeflemesini sağlayabilirsiniz. Bölge, kampanyanın yer uzantıları tarafından tanımlanan konumların merkezine alınır.
LocationGroupInfo üzerinde tanımlanan yarıçap, her bir konumun etrafında dairesel bir bölge belirtir ve bir radius nesnesi, uzunluk ve radius_units içerir. Bu yarıçap metre veya mil (LocationGroupRadiusUnitsEnum) olabilir.
LocationGroupInfo içindeki konumlar, geo_target_constant alanında belirtilen coğrafi hedefleme ölçüt kimlikleri listesine göre filtrelenebilir. Tanımlanırsa belirtilen ölçüt kimliklerinin dışında bulunan hiçbir konum hedeflenmez.