يوضّح هذا الدليل الاستهداف حسب الموقع الجغرافي وكيفية استخدام Google Ads API لإضافة ميزة "الاستهداف حسب الموقع الجغرافي" واستردادها وتعديلها في حملاتك.
ما سبب أهمية الاستهداف الجغرافي؟
تتيح لك ميزة "الاستهداف حسب الموقع الجغرافي" عرض الإعلانات على مستخدمين في منطقة جغرافية معيّنة. على سبيل المثال، لنفترض أنّك تُعلِن عن سلسلة من محلات السوبر ماركت. بدون استهداف الموقع الجغرافي، ستظهر إعلاناتك في جميع المناطق حول العالم، قد تتلقى إعلاناتك نقرات من المستخدمين في المناطق التي لا تتوفر فيها مواقع للمتاجر الكبيرة. وهذا يؤدي إلى تكلفة بينما لا يوفر إمكانية تحقيق عائد على الاستثمار. باستخدام الاستهداف حسب الموقع الجغرافي، تعرض حملاتك الإعلانات فقط في المناطق التي يتوفّر فيها متاجر سوبرماركت. يتيح لك هذا النهج أيضًا الاستهداف المباشر للعملاء الذين يبحثون محليًا عن محلات السوبر ماركت.
تتيح لك Google Ads API استهداف إعلاناتك حسب البلد أو المنطقة أو القرب من نقطة جغرافية معيّنة.
اطّلِع على مزيد من المعلومات في المقالة استهداف الإعلانات للمواقع الجغرافية.
حملات الاستهداف الجغرافي لمنطقة معيّنة
يمكنك توجيه الحملات لاستهداف أي منطقة جغرافية يتيح لها "إعلانات Google"
استهداف المواقع الجغرافية، مثل بلد أو ولاية أو مدينة أو منطقة بريدية. يتم تحديد كل موقع قابل للاستهداف بشكل فريد بواسطة رقم تعريف المعيار. يمكنك البحث عن رقم تعريف معيار باستخدام 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
. في حال تحديد أي مواقع جغرافية، لن يتم استهداف أي مواقع جغرافية خارج معرّفات المعايير المذكورة.