במדריך הזה נסביר מהם טירגוט למיקום גיאוגרפי ואיך להשתמש ב-Google Ads API כדי להוסיף, לאחזר ולעדכן את הגדרות הטירגוט למיקום גיאוגרפי בקמפיינים.
למה הטירגוט הגיאוגרפי חשוב?
טירגוט למיקום גיאוגרפי מאפשר לכם להציג מודעות למשתמשים באזור גיאוגרפי מסוים. לדוגמה, נניח שאתם מפרסמים רשת של סופרמרקטים. ללא טירגוט למיקום גיאוגרפי, המודעות שלכם יוצגו בכל האזורים בעולם, ויכול להיות שהמודעות יקבלו קליקים ממשתמשים באזורים שבהם אין לכם מיקומים של סופרמרקט. כך נוצרת עלות ואין אפשרות להחזר על ההשקעה. בעזרת טירגוט למיקום גיאוגרפי, המודעות שלכם יוצגו בקמפיינים רק באזורים שבהם יש לכם סופרמרקטים פתוחים. הגישה הזו גם מאפשרת לטרגט ישירות לקוחות שמחפשים סופרמרקטים ברמה המקומית.
בעזרת Google Ads API אפשר לטרגט את המודעות לפי מדינה, אזור או קירבה סביב נקודה גיאוגרפית ספציפית.
מידע נוסף על טירגוט מודעות למיקומים גיאוגרפיים
טירגוט גיאוגרפי של קמפיינים באזור מסוים
ניתן לטרגט קמפיינים לכל אזור גיאוגרפי שבו Google Ads תומכת בטירגוט למיקום גיאוגרפי, לדוגמה מדינה, מדינה (State), עיר או אזור דואר. כל מיקום שאפשר לטרגט מזוהה באופן ייחודי באמצעות מזהה קריטריון. אפשר לחפש מזהה קריטריון באמצעות GeoTargetConstantService.SuggestGeoTargetConstants
.
הערך resource_name
של כל GeoTargetConstant
הוא בצורה geoTargetConstants/{Criterion ID}
. לדוגמה, הערך resource_name
של מדינת ניו יורק הוא geoTargetConstants/21167
.
אפשר להוסיף יעדים גיאוגרפיים לקמפיינים באמצעות CampaignCriterionService
. קטע הקוד הבא מראה איך לטרגט את הקמפיין באמצעות מזהה קריטריון.
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::V17::Resources::CampaignCriterion->new({ # Create a location using the specified location ID. location => Google::Ads::GoogleAds::V17::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::V17::Utils::ResourceNames::geo_target_constant( $location_id)} ), campaign => $campaign_resource_name }); return Google::Ads::GoogleAds::V17::Services::CampaignCriterionService::CampaignCriterionOperation ->new({ create => $campaign_criterion }); }
מדי פעם Google עשויה להפסיק בהדרגה את השימוש בקריטריונים מסוימים של מיקום מסיבות שונות: יכול להיות לשנות את המבנה של המיקום לאזורים קטנים או גדולים יותר, לשינויים גיאו-פוליטיים וכו'. תוכלו להיעזר בשדה status
של אובייקט GeoTargetConstant כדי לקבוע אם המיקום הוא ENABLED
או REMOVAL_PLANNED
.
מידע נוסף על ההשבתה ההדרגתית של מיקומים גיאוגרפיים לטירגוט
חיפוש לפי שם המיקום
אפשר גם לחפש את מזהה הקריטריון לפי שם המיקום באמצעות
GeoTargetConstantService.SuggestGeoTargetConstants
.
הקוד לדוגמה הבא מראה איך לחפש מזהה קריטריון של מיקום לפי שם המיקום.
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.V17.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::V17::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; }
טירגוט קמפיינים לפי קרבה למיקום
יכול להיות שבמקרים מסוימים תרצו לטרגט בצורה מדויקת יותר מאשר לעיר או למדינה. לדוגמה, ייתכן שתרצו לפרסם סופרמרקטים בטווח של 10 ק"מ ממיקום החנות. במקרים כאלה, תוכלו להשתמש בטירגוט לפי מיקום גיאוגרפי קרוב.
הקוד ליצירת יעד גיאוגרפי קרוב דומה להוספה של מיקום גיאוגרפי לטירגוט, אבל צריך ליצור אובייקט ProximityInfo
במקום אובייקט 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::V17::Resources::CampaignCriterion->new({ proximity => Google::Ads::GoogleAds::V17::Common::ProximityInfo->new({ address => Google::Ads::GoogleAds::V17::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::V17::Services::CampaignCriterionService::CampaignCriterionOperation ->new({ create => $campaign_criterion }); }
אחזור יעדים גיאוגרפיים
אפשר לאחזר את היעדים הגיאוגרפיים של קמפיין באמצעות GoogleAdsService.SearchStream
. אפשר לסנן את התוצאות בקטע 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)
עדכון היעדים הגיאוגרפיים
כדי לעדכן מיקומים גיאוגרפיים לטירגוט בקמפיין, צריך לאחזר את רשימת היעדים הגיאוגרפיים הקיימים ולהשוות אותה לרשימת היעדים החדשים. לאחר מכן תוכלו להשתמש בפעולה remove
כדי להסיר את היעדים שאתם לא צריכים, ובפעולה create
כדי להוסיף את היעדים הגיאוגרפיים החדשים שנחוצים לכם (אבל הם חסרים בקמפיין הקיים).
החרגה של טירגוט גיאוגרפי
אפשר גם להחריג את LocationInfo
, אבל לא את ProximityInfo
. כדאי להשתמש בפיצ'ר הזה כשרוצים לטרגט לאזור מסוים, אבל להחריג אזור משנה (לדוגמה, כדי לטרגט את כל ארצות הברית, למעט העיר ניו יורק). כדי להחריג אזור מסוים, צריך להגדיר את השדה negative
ב-CampaignCriterion
להיות true
.
טירגוט של כמה אזורים גיאוגרפיים
בעזרת LocationGroupInfo
תוכלו להפעיל קמפיין ולטרגט מספר אזורים גיאוגרפיים. אזור מתמקדים במיקומים שהוגדרו על ידי תוספי המיקום של הקמפיין.
הרדיוס שמוגדר ב-LocationGroupInfo
משייך אזור מעגלי מסביב לכל מיקום, ומורכב מאובייקט radius
, אורך ו-radius_units
, שיכולים להיות מטרים או מיילים (LocationGroupRadiusUnitsEnum
).
אפשר לסנן את המיקומים ב-LocationGroupInfo
לפי רשימה של מזהי קריטריונים לטירגוט גיאוגרפי, שרשומים בשדה geo_target_constant
. אם הוגדרו, לא יטורגטו מיקומים שקיימים מחוץ למזהי ה-critera הנתונים.