الموقع الجغرافي المستهدف

يوضّح هذا الدليل الاستهداف حسب الموقع الجغرافي، وكيف يمكنك استخدام 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()
        }
    };
}
      

‫2,999

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::V14::Resources::CampaignCriterion->new({
      # Create a location using the specified location ID.
      location => Google::Ads::GoogleAds::V14::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::V14::Utils::ResourceNames::geo_target_constant(
            $location_id)}
      ),
      campaign => $campaign_resource_name
    });

  return
    Google::Ads::GoogleAds::V14::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.V14.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;
    }
}
      

‫2,999

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::V14::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
    };
}
      

‫2,999

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::V14::Resources::CampaignCriterion->new({
      proximity => Google::Ads::GoogleAds::V14::Common::ProximityInfo->new({
          address => Google::Ads::GoogleAds::V14::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::V14::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، يمكنك تفعيل حملة لاستهداف مناطق جغرافية متعددة. تتمحور المنطقة حول المواقع الجغرافية التي يتم تحديدها من خلال إضافات المواقع الجغرافية للحملة أو Feed اختيارية.

ينسب النطاق الجغرافي المحدّد في LocationGroupInfo منطقة دائرية حول كل موقع جغرافي، ويتكون من جسم radius وطوله و radius_units يمكن أن تكون مترًا أو ميلًا (LocationGroupRadiusUnitsEnum).

يمكن فلترة المواقع الجغرافية في LocationGroupInfo باستخدام قائمة معرّفات معايير الاستهداف الجغرافي الموضحة في الحقل geo_target_constant. في حال تحديدها، لن يتم استهداف أي مواقع جغرافية متوفّرة خارج أرقام تعريف المعايير المحدّدة.

في ما يلي بعض النصائح عند إنشاء LocationGroupInfo:

  • يجب أن تكون السمة LocationGroupInfo.feed resource_name من Feed (إذا كانت Feed مستخدمة).

  • لا يمكن تبديل LocationGroupInfo.feed إلا في إجراءات CREATE. ولا يمكنك تبديل هذا الحقل في إجراءات UPDATE.

  • يمكن أن يحدث خطأ RESOURCE_NOT_FOUND عند إضافة Feed إلى LocationGroup لأي من الأسباب التالية:

    • لم يتم العثور على Feed.
    • صفحة "Feed" غير نشطة.
    • لا يضم Feed سمات تمّ ربطها بمعايير حملة الموقع الجغرافي.

يمكن تحديد ما إذا كان يمكن استخدام Feed لـ LocationGroup من خلال الاطّلاع على إدخالات FeedMapping، ويجب أن يحتوي عنصر واحد على الأقل على FeedMapping على criterion_type بقيمة LOCATION_EXTENSION_TARGETING. إليك استعلام GAQL الذي يعرض الخلاصات ذات نوع معيار تعيين الخلاصة المناسب:

SELECT
  feed.id,
  feed_mapping.criterion_type
FROM feed_mapping
WHERE feed.id = <feed id>
  AND feed_mapping.criterion_type = LOCATION_EXTENSION_TARGETING