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

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

#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()
        }
    };
}
AddCampaignTargetingCriteria.cs
      

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]);
}
AddCampaignTargetingCriteria.php
      

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
add_campaign_targeting_criteria.py
      

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
add_campaign_targeting_criteria.rb
      

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

  return
    Google::Ads::GoogleAds::V20::Services::CampaignCriterionService::CampaignCriterionOperation
    ->new({
      create => $campaign_criterion
    });
}
add_campaign_targeting_criteria.pl
      

قد توقف 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());
    }
  }
}
GetGeoTargetConstantsByNames.java
      

#C

public void Run(GoogleAdsClient client)
{
    // Get the GeoTargetConstantServiceClient.
    GeoTargetConstantServiceClient geoService =
        client.GetService(Services.V20.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;
    }
}
GetGeoTargetConstantsByNames.cs
      

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
        );
    }
}
GetGeoTargetConstantsByNames.php
      

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})."
        )
get_geo_target_constants_by_names.py
      

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
get_geo_target_constants_by_names.rb
      

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::V20::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;
}
get_geo_target_constants_by_names.pl
      

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

في بعض الأحيان، قد تحتاج إلى استهداف منطقة أصغر من مدينة أو بلد. على سبيل المثال، قد تريد الإعلان عن محلات السوبر ماركت ضمن نطاق 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();
}
AddCampaignTargetingCriteria.java
      

#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
    };
}
AddCampaignTargetingCriteria.cs
      

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]);
}
AddCampaignTargetingCriteria.php
      

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
add_campaign_targeting_criteria.py
      

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
add_campaign_targeting_criteria.rb
      

Perl

sub create_proximity_campaign_criterion_operation {
  my ($campaign_resource_name) = @_;

  # Construct a campaign criterion as a proximity.
  my $campaign_criterion =
    Google::Ads::GoogleAds::V20::Resources::CampaignCriterion->new({
      proximity => Google::Ads::GoogleAds::V20::Common::ProximityInfo->new({
          address => Google::Ads::GoogleAds::V20::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::V20::Services::CampaignCriterionService::CampaignCriterionOperation
    ->new({
      create => $campaign_criterion
    });
}
add_campaign_targeting_criteria.pl
      

استرداد الاستهدافات الجغرافية

يمكنك استرداد الاستهدافات الجغرافية لإحدى الحملات باستخدام 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. في حال تحديدها، لن يتم استهداف أي مواقع جغرافية تقع خارج معرّفات المعايير المحدّدة.